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Introduction 

This manual describes the standard library functions. These functions are included to provide 
compatibility and portability with other computer systems. The term “standard” here is 
something of a misnomer since there is no universally accepted set of library routines. The 
functions included here are a subset of those found in most popular C environments. 

Aside from porting code from other machines, you might find the standard libraries useful for 
“quick-and-dirty” programs where you don’t really want to go through the Macintosh 
interface. 


The Libraries 

The libraries are supplied in project form so the smart linker can create the smallest code 
possible. The source code for all the standard libraries is included in your THINK C package, 
so you can modify the routine to suit your programs. 

The libraries are: 


stdio 

strings 

math 

storage 

unix 

unix_strings 

storageu 


Miscellaneous standard I/O functions. 

String handling functions. 

Math functions. 

Memory allocation functions. 

Miscellaneous functions provided for UNIX compatibility. 
UNIX string handling functions. 

UNIX memory allocation functions. 


Note: If you are using the 68881 code generation, be sure you use the 
xxx881 versions of the standard libraries. 

To use the functions in these libraries, you need add the libraries to your project and include 
the appropriate header file in your program. The appropriate #include statement is shown 
as a part of the syntax for each function. 

A function index in the back of the manual that will help you to quickly locate a function you 
need. 
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Introduction 

The stdio library provides the standard I/O routines found in most C environments. 
Functions that normally send their output to the console or to stdout open a window called 
console in THINK’s LightspeedC. 

Note; Since the stdio use the Macintosh routines to create the console 
window and to write into it, be sure you add MacTraps to your project. 

Defined Symbols 

The following symbols are defined by including stdio. h: 

BUFSIZ 

BUFSIZ, the size of an input/output buffer, is defined as 512. Buffers are used in calls to 
functions like read () and write (). 

Buffers less than BUFSIZ are less efficient, buffers larger than BUFSIZ are treated as sets of 
BUFSIZ blocks. BUFSIZ is measured in characters (or bytes), so a buffer will hold 
proportionately fewer items of a larger data type. 

BUFSIZE is an alternate symbol with the same definition. 

__console 

_console contains the file pointers for I/O to the console. The console is the keyboard and 
the screen, stdin, stdout, and stderr initially point to the console as well, but can be 
redirected to point to a file. 

A family of functions beginning with the letter c (cgets (), cprintf (), etc.) are dedicated 
to performing I/O to the console. 

EOF 

EOF, the value used to represent the end of a file, is defined as -1. Write code using EOF 
rather than -1. This will allow code to be ported to a system which does not use -1 to 
represent the end of a file (some systems use 0 to represent EOF). EOF is returned by the 
appropriate library functions when they are at the end of a file. 


For example: 
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while ( (ch = getcharO) != EOF) 

{ 

} 

errno 

errno is a global variable, located in stdio, holding the last error message number from any 
stdio I/O routine. 

Note; See the following “Error Messages” section. 


FILE 

FILE, the structure which holds the file descriptor, is defined below. This type definition 
creates a type called FILE which can be used anywhere you could use one of C's built in 
types (int, char, long, ...). Because of the library functions, you will probably never have 
to access the internals of a FILE directly. The fields are included here just in case. 

Note; This manual will use “file descriptor” to refer to the C structure which 
holds the file information. Kernighan and Ritchie use “file descriptor” to refer 
to the number assigned to each open file. This manual will call that number 
the “file number”. A “file number” is a pointer to a file descriptor (FILE 
*) - 

typedef struct { 

int refnum; /* Operating System (OS) ref number */ 

int last_error; /* Last error produced by access to this file */ 

unsigned user_sys:l; /* Single bit flags indicating: */ 

/* user buffer instead of system buffer */ 

InUse:1; /* this file descriptor is in use */ 

StdStream:1; /* standard stream (keyboard, CRT,...) */ 

rd:l; /* read permission */ 
wr:1; /* write permission */ 

look_full:l; /* look ahead character is valid */ 
char look_ahead;/* Next char to be returned by getc() */ 

Handle filebuf; /* Handle of OS buffer for this file */ 

} FILE; 


_file 

_f ile is an array of FILE (_f ile[_NFILED which is used to hold the file descriptors of all 
the files which are open. _f ile is used implicitly by all the file access functions. When you 
use open () to open a file, a FILE in _f ile will be dedicated to that file, and the index will 
be returned as a file number. If you use f open () to open a file, the file pointer (FILE *) to 
the FILE in _f ile is returned instead of the file number. File I/O functions require either a 
file number or a file pointer as an argument, f ileno () returns the corresponding file when 
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given a file pointer. To go the other way, use _f ilelfn], the file pointer corresponding to file 
number f n. 

See also: FILE, f open (), open (), f ileno () 

_NFILE 

_NFILE, the number of files that can be open at one time, is defined as 15. 

NULL 

NULL, the value of a pointer that is pointing to nothing, is defined as 0 L. NULL is returned by 
many library functions (eg: calloc () or sbrk ()). It is typically used to indicate an error by 
functions which return pointers. On every system, NULL will point to nothing, although its 
value will not always be 0 L. 

stdin,stdout,stderr 

The three standard I/O file pointers (to the input, output, and error) may be used anywhere 
that a function takes a FILE * as an argument. For example, getc(stdin) gets a single 
character from stdin; fputs("Hello", stdout) puts the string Hello on the standard output. 
Some functions use the standard I/O automatically, most notably: get char () and 
putchar (), gets () and puts (), scant () and printf (). Library functions send their 
error messages to stderr automatically; your procedures can use it too or can send error 
messages into other files. The tables of input and output functions in the introduction to this 
section show which functions to use for stdin and stdout. 

I/O from/to stdin and stdout can be redirected so that a file is used instead of the 
console. This allows programs to be written and compiled using stdin and stdout, and 
then connected to a file at run time. 

Experienced C programmers from other systems should take note of the cxxxxx family of 
functions (cputs, cprint, cgets, cscanf, as well as putch, getch, getche) which 
send their output to the console automatically. I/O to/from the console using these functions 
cannot be redirected. The console I/O functions are included in the tables in the 
introduction. 
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LIBRARY 

SYNTAX 

DESCRIPTION 


RETURN VALUE 
SEE ALSO 


• GET A STRING FROM THE CONSOLE 

cgets 

stdio 

#include <stdio.h> 
char *cgets(char *s) ; 

cgets () gets a string from the console (the keyboard) and puts it into 
the character string pointed to by s. The string is terminated when a 
carriage return (OxOD, '\r') is entered from the keyboard The input is 
always echoed to the screen. 

(Note that this is not the usual C definition of a string. The carriage return 
is stripped off by cgets, and the string is stored internally in the standard 
C fashion - as a character array terminated by a null character (' \0')). 

Be sure that s i s a character array long enough to handle any anticipated 
input, or else the excess input will be written into the memory that follows 
s, destroying whatever was there before. 

cgets () echoes input to the screen. 

A pointer to string s; NULL if error. 

cputs() 
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LIBRARY 

SYNTAX 


DESCRIPTION 


SEE ALSO 


• CLEAR LAST ERROR FLAG OF A STREAM 

clearerr 

clrerr 

stdio 

#include <stdio.h> 

void clearerr(FILE *stream); 

void clrerr(FILE *stream); 

clearerr () resets the last_error flag of the File descriptor of the 
given stream. The last_error flag could be accessed directly by 
the syntax: 

stream -> last_error 
stream can be any pointer to a FILE. 

clrerr () is a synonym for clearerr () . It too clears the last error flag 
of a given stream. 

FILE 
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LIBRARY 

SYNTAX 

DESCRIPTION 


• enable/disable "Click to Continue" on exit 

Click_on 

stdio 

#include <stdio.h> 

void Click_On(Boolean flag); 

This function controls the "click mouse to continue" option. If flag is 1, 
the option is enabled; if flag is 0 the option is disabled. I f this option is 
enabled, when a program that uses stdio terminates, a window (titled "Exit 
Window") will appear. Only when the user clicks in the close box, 
presses the return key, or (if the menus were created by stdio) selects the 
Quit command from the File menu will the program actually exit. This 
option is initially enabled. 
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LIBRARY 

SYNTAX 

DESCRIPTION 


RETURN VALUE 
SEE ALSO 


• CLOSE ALL OPEN FILES 

_closeall 

stdio 

#include <stdio.h> 
int closeall(void); 

_closeall () closes all open files that were opened via a call to open 
() or fopen (). 

_closeall () is called automatically upon successful program 
termination. 

Call close () or f close () to close a single file. 

The number of files that could not be closed, 
close (), fcloseO, open (), fopen () 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 

SEE ALSO 


• FORMATTED PRINT TO THE CONSOLE SCREEN 

cprintf 

stdio 

#include <stdio.h> 

int cprintf (char *format, ...) ; 


cprintf () does a printf to the console screen, printf stands for 
formatted print, and is the most general way to output text and variables, 
whether to the console (cprintf () ) , a File (fprintf () ), stdout 
(printf () ) or to a string in memory (sprintfO). SeeprintfO 
for a complete description of the format rules. 

The number of characters sent to the output stream if successful; EOF 
if an error occurs. 

printf (), sprintf (), fprintf () 
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LIBRARY 

SYNTAX 

DESCRIPTION 


EXAMPLES 


SEE ALSO 


• PUT STRING TO THE CONSOLE SCREEN 

cputs 

stdio 

#include <stdio.h> 
void cputs(char *s) ; 

cputs () puts a null terminated C\0') string on the user's console screen. 
Unlike puts (), cputs does NOT automatically send a carriage return 
0 \ r') or a newline ('\n') when it reaches the end of the string. However, 
the string may explicitly include '\r' or '\n' characters. The string can be 
a variable or a constant, as shown in the example. The null character is 
not written to the console. 

#include <stdio.h> 
char *s, buf[20] 
s = gets(buf); 
cputs(s); 

cputs("\r\nDONE\r\n") ; 
cgets (),puts (), fputs() 
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LIBRARY 

SYNTAX 

DESCRIPTION 


RETURN VALUE 
SEE ALSO 


• READ TEXT AND DATA FROM CONSOLE 

cscanf 

stdio 

#include <stdio.h> 

int cscanf (char *format, ...); 

cscanf () does a s c a n f () from the keyboard of the console, 
scanf () stands for formatted scan, and is the most flexible way to read 
text in and convert it into a mixture of strings and numeric values. 

Note that cscanf () takes a variable number of arguments -- it can read 
values into a variable number of variables, format is a string telling 
what sort of variables to expect, in what order, and with what text 
intermixed. 

NOTE : args are POINTERS to the variables to read into, NOT the 
variables themselves. Remember to use the & operator to get the address 
of a variable. If you don't, you will overwrite random memory. 

Refer to the description of scanf () for complete information about the 
format and args arguments. 

scanf () and printf () are conceptually inverse functions (and 
therefore, cscanf () is to scanf () as cprintf () is to printf ()). 

Number of items successfully input. 

scanf (),fscanf (),sscanf(), printf() 
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LIBRARY 


DESCRIPTION 


• TESTS WHETHER CHARACTER C HAS CHARACTERISTIC TYPE 

ctype 

stdio 


#include <stdio.h> 
int istype(char c) ; 

There is a family of functions to make various tests on a character. All 
take a single character as an argument and return an int value. The 
return value is non-zero if the condition is true, 0 if it is false. The istype 
functions (with all numeric values in decimal) are: 


isalnum(c) 
isalpha (c) 
isascii (c) 
iscntrl (c) 
iscsym (c) 

iscsymf (c) 

underscore) 
isdigit (c) 
isgraph (c) 

islower (c) 
isodigit (c) 
isprint (c) 

ispunct (c) 


isspace (c) 
of: 

isupper (c) 
isxdigit (c) 


True if c is a letter (a-z, A-Z) or a digit (0-9) 

True if c is a letter (a-z, A-Z) 

True if c is an ASCII character (ASCII 32-128) 

True if c is a control character (ASCII 0-31) 

True if c is a character that can appear in a valid C 
identifier (a letter, digit, or underscore) 

True if c is a character that can appear as the first 
character of a valid C identifier (a letter or an 

True if c is a digit (0-9) 

True if c is any printing character other than a space 
(ASCII 0 41 through 017 6) 

True if c is a lower case letter (a - z) 

True if c is an octal digit (0-7) 

True if c is a printable character (ASCII 32-255; but not 
127) 

True if c is a punctuation character. A punctuation 
character is one of: 

# $ % & * ( ) " ' <>/? \ I []{}-_ = 

+ . 

True if c is a space character. A space character is one 

space, \t, \v, \n, \f or \r. 

True if c is an upper case letter (A-z) 

True if c is a hex digit (0-9, A-F, a-f). 
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RETURN VALUE 
SEE ALSO 


The functions all use a predefined table called_ctype which contains a 

mask bit for each type of character, as listed below: 


_alpha_ 

1 

_ascii_ 

16 

_digit_ 

2 

_cntrl_ 

32 

hex 

4 

_punct_ 

64 

_octal_ 

8 

_space_ 

178 


With the exception of is upper () and is lower () , which are true 
functions, these routines are macros that test the mask settings for the 
respective character. 

non-zero if the condition is true; 0 if the condition is false, 
toascii (), toupper (), tolower () 
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LIBRARY 

SYNTAX 

DESCRIPTION 


• TURN PRINTER ECHO ON OR OFF 

Echo_to_PrInter 

stdio 

#include <stdio.h> 

void Echo_to_Printer(Boolean flag); 

Call this function with the argument TRUE to turn on printer echoing. 
When printer echoing is on, the console window text output will be 
echoed to the printer. If input is being echoed to the console window, it 
will be echoed to the printer as well. 

Call this function with the argument FALSE to turn off printer echoing. 
This is the default condition. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 
SEE ALSO 


• CLOSE A FILE 

fclose 

stdio 

#include stdio.h 

int fclose (FILE *stream) ; 

fclose () closes the given stream, flushing the I/O buffer if necessary. 
The file descriptor in _file used by stream is then available for 
another file. 

The difference between fclose () and close () is that fclose () 
takes a file pointer as its argument while close () takes the file 
descriptor number. 

0 if success; EOF if error. 

open(),close(), _closeall() 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 

SEE ALSO 


• TEST WHETHER AT END OF STREAM 

feof 

stdio 

#include <stdio.h> 
int feof (FILE *stream); 

feof () is used to test whether a previous I/O call to the given stream 
caused an EOF error (such as trying to get a character after having reached 
the end of the file). 

Naturally, if you use clrerr () or clearerr () to clear the error flag of 
that stream, feof () will no longer report an EOF error. Similarly, a 
later call with another type of error will also erase the EOF error flag. 

non-zero if last_error flag in the stream structure is an EOF error; 
0 if last_error is not an EOF error. 

FILE, clrerr(), clearerr(), ferror() 
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• TEST WHETHER I/O ERROR FLAG IS SET FOR STREAM 

ferror 

LIBRARY stdio 

SYNTAX #include <stdio.h> 

int ferror(FILE *stream); 

DESCRIPTION ferror () tests whether any sort of I/O error flag is set for the given 

stream. clrerr() and clearerr () will reset the error flag. 

RETURN VALUE non-zero if any I/O error had occurred; 0 if the last_error flag in the 
stream structure is not set. 

SEE ALSO feof (),clrerr(), clearerr() 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 
SEE ALSO 


• FLUSH I/O BUFFER OF STREAM 

ffhish 

stdio 

#include <stdio.h> 

int fflush(FILE *stream); 

f flush () flushes the I/O buffer of the specified stream. This is often 
done if an I/O error has occurred and you want to start anew. Buffers 
should also be flushed before closing files. 

Note that f flush () returns 0 if successful. 

0 if success; EOF if an error occurred while trying to flush the buffer, 
fopen () 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 

SEE ALSO 


• GET A CHARACTER FROM STREAM 

fgetc 

stdio 

#include <stdio.h> 

int fgetc (FILE *stream); 

fgetc () reads in the next character from the given stream. Since 
f getc () returns the integer value of the character, it can be used to get 
bytes from a binary file. 

Use f read () or fgets () to read in multiple characters more easily and 
efficiently, and use f scanf () to read text and data directly into variables. 

EOF if error or at the EOF of the stream; the integer value of the character 
otherwise. 

freadO , fgets (), fscanf (), getc (), gets (), read(), scanf () 
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LIBRARY 

SYNTAX 

DESCRIPTION 


• GET A STRING FROM STREAM AND PUT IN ARRAY 

fgets 

stdio 

#include <stdio.h> 

char *fgets(char *s, int n, FILE *stream) ; 

fgets () tries to read the next n characters from stream and store 
them in the character array s . It adds the null character C\0') to the 
character array after the nth character, and returns a pointer to s. 
Therefore, s must be declared as a character array large enough to hold 
n+1 characters. 

Two events will stop fgets () before it has read in n characters. First, if 
it reads in a newline ('\n'), it adds the '\n' to the string, adds the '\ O', and 
returns s. Second, if fgets () reads in an EOF, it considers it an error, 
sets the EOF error flag, stops trying to read in characters from the file, and 
returns a NULL pointer. 

Use f error to find out which error occurred last. 


RETURN VALUE 
SEE ALSO 


NULL if error or if EOF; s (the first argument) otherwise, 
fgetc(), fread(), fscanf(), ferror() 
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LIBRARY 

SYNTAX 

DESCRIPTION 


• OPEN A FILE 

fopen 

stdio 

#include <stdio.h> 

FILE *fopen(char *pathname, char *type); 

fopen () opens a stream to pathname by creating a file descriptor as 
well as doing the necessary operating system work, fopen () returns the 
pointer to the newly created file descriptor. The file is opened according 
to the type (the values for type are described below). The effect of 
type depends on whether the given pathname can be found: a new 
file is created if pathname does not exist, pathname is opened if it 
already exists. 

Files can also be opened with open (), which returns the file number in 
the array of file descriptors rather than the pointer to the file descriptor. 
Use open (), close (), etc. instead of the standard C library file calls 
fopen () , fclose () , etc. when you are concerned with UNIX 
compatibility. 

fopen () and open () are not synonymous. Not only do they interpret 
their arguments differently, their arguments are of different types. Note 
that some library functions access a file by its file pointer, others by its file 
number. Therefore, your choice of fopen () vs. open () will dictate 
your choice of other library routines. 

The values for type are strings and are: 

" r " open an existing file for reading. 

"w” create a file for writing if it does not exist; delete and then 
recreate a file for writing if it already exists. 

"a M create a file for writing if it does not exist; open a file and place 
pointer at the EOF for appending if it already exists. 

”r+” open an existing file for reading and writing. 

”w+” create a file for reading and writing it if does not exist; delete and 
recreate a file for reading and writing if it already exists. 
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RETURN VALUE 
SEE ALSO 


"a+" create a file for reading and writing if it does not exist; open a file 
and place pointer at the EOF for appending and reading if it 
already exists. 

b binary file: '\r' not converted to '\n' on reads, '\n' not converted 

to ' \ r' on writes. 

b is not in quotes because it is added to one of the other values 
for type. For example, "rb", "wb", "ab", "r+b", "w+b", 
"a+b". "b" alone is meaningless and is an error. 

Note that the type argument is a character pointer, not a single character. 
Therefore, newfile = fopen (" foo", "r") is legal while newfile 

= fopen ("foo", ' r' ) will not operate as intended, and will have 

unpredictable results. 

NULL if error; the pointer to the file descriptor if success. 

open (), _file, FILE, fileno (), fclose () , fflush (), f read () , 
fwrite() 
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LIBRARY 

SYNTAX 

DESCRIPTION 


RETURN VALUE 


OPEN A NEW STDIO WINDOW 

fopenw 

stdio 

#include <stdio.h> 

FILE *fopenw(char *title, Point upperLeftCorner, 
StdWindowOptions *optionsPtr); 

fopenw opens a new window with the specified title at the designated 
position (in global coordinates). 

optionsPtr is a pointer to a StdWindowOptions structure as defined in 
fopenw. h. If the pointer is NULL (OL), then the window will be created 
with the following defaults: a 24-by-80 window, visible cursor, input 
echoed, tab width of 4 spaces, window brought forward on output to it 
(including echoing of input), grow box, draggable, go-away box, 
scrolling, and line wrap-around. (On big-screen Macintoshes, the default 
screen will be larger.) After calling fopenwO, the memory pointed to by 
optionsPtr is no longer needed. 

Returns an ordinary FILE pointer variable which can be passed to 
fprintf, f close, etc. 
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LIBRARY 

SYNTAX 

DESCRIPTION 


RETURN VALUE 

SEE ALSO 


• FORMAT AND PRINT TO A FILE 

fprintf 

stdio 

#include <stdio.h> 

int fprintf (FILE *stream, char *format, ...); 

fprintf () formats and prints output to the specified stream. It is used 
to print a combination of text and data to the file pointed to by stream. 
In all other ways, it is identical to print f () which does a formatted print 
to the standard output. See printfO for a description of the format 
and optional args arguments. 

fputc () , fputs () , and f write () put a character, a string, and a 
block of text in a file, respectively: they are simpler and more efficient, but 
are not as general and cannot deal with numeric data. 

f scanf () is the inverse of fprintf (): it does a formatted read of text 
and data from a file. 

The number of characters sent to the output stream if successful; EOF 
if an error occurs. 

printf (), cprintf (), sprintf (), fputc () , fputs () , 
fwrite (),fscanf () 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 

SEE ALSO 


• PUT A CHARACTER INTO A FILE 

fputc 

stdio 

#include <stdio.h> 

int fputc(char c, FILE *stream) ; 

fputc () adds a single character c to stream. See fputs (), 
f write (), and f printf () for ways to add strings, blocks of text, or 
combinations of text and data to a file, putc () puts a single character to 
the standard input. 

EOF if error (such as a read only file); c, the integer value of the 
character, if success. 

putc (),fputs(), fwrite(), fprintf() 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 
SEE ALSO 


• PUT A STRING INTO A FILE 

fputs 

stdio 

#include <stdio.h> 

int fputs(char *s, FILE *stream); 

fputs () puts a null terminated (* \0 1 ) string to stream. The 1 \ 0 ' is 
not written to the file. 

0 if successful; otherwise EOF. 

cputs(), puts(), fprintf(), fwrite (), fputc () 
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LIBRARY 

SYNTAX 

DESCRIPTION 


EXAMPLES 

RETURN VALUE 

SEE ALSO 


• READ A BLOCK OF CHARACTERS FROM A FILE 

fread 

stdio 

♦include <stdio.h> 

int fread(char *ptr, unsigned size_of_ptr, int 
count, FILE *stream); 

fread () tries to read count items from stream and store them in the 
block pointed to by ptr. The size_of_ptr field should be an 
unsigned integer that is the size of the object pointed to by the pointer. If 
f read reaches the end of the File before it has read count bytes, it sets 
the EOF error flag and returns the number of bytes it was able to read. 

read () is a similar function to read a block of data from a file, read () 
accesses the file by its file number rather than its file pointer, f scanf (), 
f gets (), f getc () and getc () are other functions to get data from a 
file. 

♦include <stdio.h> 
struct F00 { 

int a; 
char b; 

} foo[3]; 

fread (&foo[0], sizeof(struct F00), 3, stdin); 

/* reads 3 items of sizeof F00 into buffer 
pointed to by foo from stdin */ 

0 on immediate end of file or error (use f error () and f eof () to tell); 
otherwise the number of items transferred. 

read(), fscanf(), fgetc(), fgets(),getc () 
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SYNTAX 

DESCRIPTION 


RETURN VALUE 
SEE ALSO 


• REDIRECT OUTPUT TO DIFFERENT FILE 

freopen 

stdio 

#include <stdio.h> 

FILE *freopen(char *filename, char *type, FILE 
*stream); 

freopen () closes the file whose file descriptor is stream and calls 
fopen (), passing the filename and type. The file will be opened 
using the same string that was used to close it. 

This routine is used to redirect a stream's output to a different file. For 
example, after the call freopen ("abc", "w", stdout), all output to 
stdout will go to the file "abc". 

NULL if error (sets an error code in errno); otherwise stream, 
fopen (), fclose () 
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LIBRARY 

SYNTAX 

DESCRIPTION 


RETURN VALUE 
SEE ALSO 


• SCAN AND FORMAT INPUT FROM A FILE 

fscanf 

stdio 

#include <stdio.h> 

int fscanf (FILE *stream, char *format, ...) ; 

f scanf () does a formatted scan taking input from stream. It breaks 
the input up into characters, strings, integers, etc. according to format, and 
stores that formatted data in the variables pointed to by args. There can 
be a variable number of args. The args must be pointers to variables, 
not the variables themselves. See scanf () for a description of the format 
argument. 

CAUTION : The most common mistake when using f scanf () is to use 
the variables themselves rather than the pointers to the variables, 
f scanf () needs to know the address of the variables it will use to store 
data, not their present values. Failing to use addresses to store the values 
will overwrite random memory. See the examples in scanf (). If 
f scanf () runs out of arguments before reaching the end of s, arbitrary 
values from the stack are used as the address of the arguments and 
overwrite random memory. 

Similar functions are scanf () (from stdio), cscanf () (from the 
console), and sscanf () (from a string). Other functions to get data from 
a file include getc (), fgetc () , fgets () , read () , and f read (). 
f print f () does a formatted print of data to a file. 

Number of items successfully input. 

scanf (),cscanf (),sscanf() 
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RETURN VALUE 
SEE ALSO 


• MOVE TO A DIFFERENT POINT WITHIN A FILE 

fseek 

stdio 

#include <stdio.h> 

int fseek(FILE *stream, long offset, int type); 

f seek () allows for non-sequential I/O to a stream. When a file is 
opened for reading or writing, a "logical cursor" is placed at the beginning 
of the file. That logical cursor is advanced through the file with each read 
or write, fseek () and its cousin lseek () move that logical cursor, 
(lseek () differs in two main ways: it takes a file number rather than a 
pointer to the file descriptor and it returns a long rather than an int). 

The type argument determines where the seek begins: 

0 offset relative to the beginning of the file 

1 offset relative to current file position 

2 offset relative to the end of file 

offset is simply the count in bytes from the starting point specified by 
the type argument. Note that offset is a long, and can be either 
positive or negative. 

FILE *fd; 

fseek(fd,OL,0); /* move to start of file */ 
fseek(fd, 20L, 1); /* move forward in file 20 bytes*/ 

fseek(fd, OL, 2); /* move to end of file */ 

Zero if success, non-zero if error. 

lseek () 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 
SEE ALSO 


• RETURN CURRENT POSITION WITHIN FILE 

ftell 

stdio 

#include <stdio.h> 

long ftell (FILE *stream) ; 

ftell () returns the current position within the file, ftell () returns 
1L if an error has occurred. 

Current position within file if successful; -1L if error, 
tell (), fseek () 
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DESCRIPTION 


RETURN VALUE 

SEE ALSO 


• WRITE A BLOCK OF CHARACTERS TO A FILE 

fwrite 

stdio 

#include <stdio.h> 

int fwrite(char *ptr, unsigned size_of_ptr, int 
count, FILE *stream); 

fwrite () writes a block of data to stream, count is the number of 
items to be written, and pt r i s a pointer to the start of the block. 
size_of_ptr is the size of the item to write. 

write () also writes a block of data to a file, write () differs in two 
ways: it accesses the file by its file number and it simply writes a specified 
number of bytes to the file. 

f print f () , fputs () , fputc () , and putc () are other functions 
which add data to a file, f read () is the inverse of fwrite () . 

0 if error (check with f error () and f eof ()); otherwise number of 
items transferred. 

fread(), write(), fprintf(), fputs(), fputc (),putc() 


33 



Standard Libraries Reference 


LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 

SEE ALSO 


• GET NEXT CHARACTER FROM FILE 

getc 

stdio 

#include <stdio.h> 

int getc(FILE *stream) ; 

This is a macro calling fgetc () 

getc ( ) gets the next character from stream, getc ( ) returns that 
character as an int so that it can be used to get bytes from a binary file. 

fgetc () also gets a character from a file, while f scanf (), f read (), 
f gets () and read () get larger groups of data, putc () is the inverse 
of getc () and adds a character to a file. 

The integer value of the next character from stream; EOF on end of file 
or error. 

fgetc (),fgets(), fscanf(), fread(), read(), putc () 
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•GET NEXT CHARACTER FROM KEYBOARD, DON'T ECHO 

getch 

stdio 

♦include <stdio.h> 
int getch(void); 

getch () gets the next character from the keyboard The character is not 
echoed, (getche () is the same as getch () except the character is 
always echoed to the screen). 

Note that the return value is an int, not a char. This is so that getch () 
can return all possible characters (0-255) and EOF (-1). 

The integer value of the character; or EOF on end of file or error. 

getchar(), getche() 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 
SEE ALSO 


• GET NEXT CHARACTER FROM STDIN 

getchar 

stdio 

#include <stdio.h> 
int getchar () 

getchar () is a macro calling f getc ( stdin) 

getchar () gets the next character from stdin. The character is not 
echoed to stdout. Note that the return value is an int, not a char. 
This is so that getchar () can return all possible characters (0-255) and 
EOF (-1). 

The integer value of the character; or EOF on end of file or on error, 
getc (),getch (), getchar(), getche(), f getc() 
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SEE ALSO 


• GET NEXT CHARACTER FROM KEYBOARD, ECHO TO SCREEN 

getche 

stdio 

#include <stdio.h> 
int getche(void) ; 

getche () is the same as getch () except that it echoes the character to 
the screen. See the description of getch (). 

The integer value of the character from the keyboard; or EOF on end of 
file. 

getc(), getch (), getchar (), getche (), fgetc() 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 

SEE ALSO 


• GET CHARACTERS FROM STDIN TILL NEWLINE AND STORE IN S 

gets 

stdio 

#include <stdio.h> 
char *gets(char *s) 
char *s; 

gets () reads characters in from stdin to the character array s. When 
it reads in a newline (* \n'), the 1 \n 1 is discarded and a null character 
C 1 \ 0 ') is added to s to terminate the string. Therefore, s must be large 
enough to hold one more character than is anticipated. 

fgets () and cget s () get strings from a file and from the console 
respectively. They have some differences so check their descriptions. 

getchar () and scanf () also read in data from stdin. 

s, the first argument, is returned if success; NULL if EOF or error (use 
f error () and f eof () to determine cause). 

cgets (), fgets(), getchar(), scanf() 
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RETURN VALUE 
SEE ALSO 


• GET CURSOR POSITION 

getxpos 

getypos 

stdio 

#include <stdio.h> 
int getxpos(void) 
int getypos(void) 

These functions return the x and y coordinates of the cursor in the current 
window. 

x or y coordinates of the cursor, 
setwindow 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 


• GET THE SCREEN BUFFER OF STDIO WINDOW 

Get_ScreenPtr 

stdio 

#include <stdio.h> 

char *Get_ScreenPtr(FILE *windowFileVar); 

This function returns the address of the screen buffer for the window 
associated with the FILE variable windowFileVar. The buffer can be 
treated as a two-dimensional array of characters whose size is given by the 
maxcol and maxrow fields of the StdWindowOptions structure defined in 
fopenw.h. 

The address of the screen buffer associated with windowFileVar. 
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• MOVE CURSOR ON THE SCREEN 

gotoxy 

stdio 

#include <stdio.h> 
void gotoxy(int x,int y); 

gotoxy () simply moves the cursor on the screen to the given (x,y) 
character position (as in standard I/O). 

0,0 is in the top left corner of the screen. The range of possible 
coordinates will depend on the point size. For the default font (25 lines 
by 80 characters), the bottom right corner coordinates will be 8 0,25. 
Character positions are calculated for a monospaced font. 

Note that this is different from move () , which uses a pixel-based 
coordinate system. 

circle (),label (),line(), move(), point () 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 

SEE ALSO 


• TEST WHETHER KEYBOARD WAS HIT 

kbhit 


stdio 

#include <stdio.h> 
int kbhit(void) ; 

kbhit () tests whether there is a character available from the keyboard 
without getting the character, kbhi t () is provided so that you can write 
a loop to watch until the keyboard is hit, doing other work or with a 
timeout, getch () and similar functions have no timeout, and so take 
control for an indefinite period of time. Once the keyboard is hit, you can 
use getch () and know that it will return. 

1 if a keyboard character is available; 0 if no keyboard character is 
available. 

getch (), getche() 
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DESCRIPTION 

RETURN VALUE 
SEE ALSO 


•call A Procedure before program exit 

onexit 

stdio 

#include <stdio.h> 
typedef void (*Proc)(); 

Proc *onexit (Proc proc) 

Arrange for C function Proc to be called just before program exit Proc 
is called with no arguments. Up to 32 Proc routines may be specified. 
They are called in the reverse order in which they were supplied to 
onexit () . 

NULL if onexit () was unsuccessful; or Proc if successful, 
exit (), _exit () 
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LIBRARY 

SYNTAX 

DESCRIPTION 


• PRINT AND FORMAT TO STDOUT 

printf 

stdio 

#include <stdio.h> 

int printf(format {, args}) 

char *format; 

printf () is the easiest way to output a mixture of text and values of 
variables (character, numeric, and string) to stdio. Other versions of 
printf ( ) , such as fprintf () , sprintf () , cprintf () , 
vprintf (), vf printf (), vsprintf (), and vcprintf () , use the 
same argument conventions except as noted in their own descriptions. 
The versions differ in where the output is sent. 

printf () takes a variable number of arguments. The first argument, 
format, is required. It is a string containing text and format specifiers. 
The format specifiers tell how to interpret and format the variable number 
of args that follow. 

The args arguments), written in braces above to indicate that it is 
optional and may be repeated, is a list of all the variables that this 
printf () statement will take data from. Make sure that there is one 
variable argument of the correct size for each format specifier in format 
requiring data. Arguments must also be of the right type. For example, if 
the format specifier specifies a string, the argument must be a char*. If 
the number of arguments, or the argument types, do not match the 
number and type of format specifiers, expect unpredictable results. 

Format specifiers begin with the character % and include zero or more of 
the following conversion specification elements: 

% [option flags] [field size] [.precision] [size] 
conversion 

Some of these elements are optional, but if present, they must be specified 
in the order in which they are described below. 

Option Flags (optional): 

Left adjust output in field, pad on right (default is to right justify). 
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0 Use zero (0) rather than space for the pad character. 

+ Always produce a sign, either + or — 

space Always produce either the — sign or a space. 

# Use a variant of the main conversion operation. (See the 

description of conversion operations below for details.) 

Field Size Specification (optional): 

The minimal field width, expressed as a decimal integer, a rg will be 
printed in a field at least this wide. If arg is shorter than field, field will be 
padded on the side determined by the field adjusting flags. The pad 
character is normally a space. The pad character is set to zero if the field 
width is given with a leading 0. For example: 

printf("%03 d", 2); 


prints: 


002 

with width=3, zero padding. (The zero padding does not imply octal 
values.) 

Precision Specification (optional): 

The precision specification identifies the maximum number of characters 
to be printed from a string or the number of characters to be printed to the 
right of the decimal point for a long or double. 

It consists of a period (.) followed by an optional decimal integer. If the 
integer is omitted, a precision of 0 is assumed. This is not the same as 
omitting the precision specification entirely. 

An asterisk (•) can also follow the period; in this case, the appropriate arg 
(selected by its corresponding position in the argument list) is used to 
specify the precision. This argument must be an int. 

Argument Size Specifications (optional): 

1 argument is a long 
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h argument is a halfword (a short) 

Conversion Characters (required): 

c argument is a single character 

d argument printed in signed decimal 

e, E argument is printed in signed decimal floating point format 
([ - ] d. ddde+-dd). One digit appears before the decimal point, 
and the precision specifies the number of digits to be printed 
after the decimal point. The only difference between e and E, is 
that in the latter case, the exponent is introduced by the letter E 
rather than the letter e. 

f argument is printed in signed decimal fixed point format ([ - 

] ddd.dddd). The precision specifies the number of digits to 
be printed after the decimal point. If precision is missing, 6 
digits are output; if precision is 0, no decimal point appears. 

g, G Use the f or e format, whichever is smaller. G will cause E to be 
used instead of e. 

o argument is printed in unsigned octal. 

s argument is a string. Print until null character or have filled field 

specified by precision. 

u argument printed in unsigned decimal. 

x argument printed in unsigned hexadecimal, using the digits 

0123456789abcdef 

X argument printed in unsigned hexadecimal, using the digits 

012345678 9ABCDEF 

% print a %, no argument used 
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EXAMPLES 


RETURN VALUE 
SEE ALSO 


/* print text string followed by a newline. 

It contains no format specifiers, so 
requires no arguments. */ 
printf("simple text\n"); 

/* print n = 3; %d is the format specifier 
to print a decimal number */ 
int n; 
n = 3; 

printf(”n = %d”, n); 

/* print a date and time in the form: 

weekday, month, day, hour:minute */ 
char *weekday, *month; 
int day, hour, min; 

printf(”%s, %s, %d, %.2d:%.2d”, weekday, month, 
day, hour, min); 

The number of characters printed. 

scanf (),cprintf(), sprintf() , vprintf() 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 
SEE ALSO 


• PUT A CHARACTER INTO A FILE 

putc 

stdio 

#include <stdio.h> 

int putc(char c, FILE *stream); 

putc () adds c to stream, putc () is a macro definition for fputc (). 

Other functions which put characters into a file are: fputs (), 
f printf (), vfprintf (), write (), and fwrite (). putch () puts 
a character onto the screen and put char () puts a character onto 
stdout. 

The character argument if success; EOF if failure 

fputc, fputs(), fprintf() , vfprintf(), write(), fwrite (), 
putchar 
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SEE ALSO 


• PUT A CHARACTER ON SCREEN 

putch 

stdio 

#include <stdio.h> 
void putch(char c) ; 

putch () puts a single character to the screen. Unlike putc () and 
f putc () , which put a character to a file, or putchar (), which puts a 
character into stdout, it is not possible for putch () to fail because the 
screen will always be there. 

putch () returns nothing. 

cputs (), cprintf (), and vcprintf () also send characters to the 
screen. 

putc(), fputc(), putchar(), cputs(), cprintf (), vcprintf () 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 
SEE ALSO 


• PUT A CHARACTER TO STDOUT 

putchar 

stdio 

#include <stdio.h> 
int putchar(char c) ; 

putchar () is a macro which expands to fputc (c, stdout). 
putchar () sends a single character to stdout. The other functions 
which send data to stdout are puts () and printf () . 

The character argument if success; EOF if error. 

cputc (), putch (), fputc(), puts(), printf () 
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DESCRIPTION 

RETURN VALUE 
SEE ALSO 


• PUT A STRING TO STDOUT 

puts 

stdio 

#include <stdio.h> 
int puts(char *s) ; 

puts () puts the characters from string s to stdout until it reaches a null 
byte (' \ 0 ') signalling the end of the string. The ' \ 0 ' is discarded, and 
a carriage return ( ' \r') is written to stdout. There are some 
differences between puts () and cputs () (put string to console) and 
fput s () (put string to file), so check the descriptions before using them, 
printf () andputcharO also send output to stdout. 

0 if success; EOF if failure. 

fputs() , cputs (), printfO, putchar() 
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SYNTAX 

DESCRIPTION 


EXAMPLES 

SEE ALSO 


• MOVE I/O POSITION TO START OF FILE 

rewind 

stdio 

#include <stdio.h> 

void rewind(FILE *stream) ; 

rewind () sets the I/O position back to the start of the file. The I/O 
position is moved automatically during I/O, as well as explicitly by 
lseek() andfseek(). 

A call to f seek(fd, OL, 0) is the same as a call to rewind (f d). 
rewind(fd); 

fseek(fd, OL, 0); /* same as rewind */ 
f seek (), lseek () 
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• SCAN AND FORMAT INPUT FROM STD IN 

scanf 

stdio 

#include <stdio.h> 
int scanf (char *format , 

scanf () reads characters in from stdin and formats them into data. 
That data is stored in variables. 

For example, if scanf () is expecting an integer and reads in the 
characters ”371”, it converts it from a character string into the integer 
value 371, and stores it in a variable pointed to by one of args. 

scanf () can read in different kinds of data in a single call, so it provides 
an extrememly useful and flexible way to get input. 

cscanf (), fscanf (), and s s c a n f () use the same argument 
conventions as scanf () except when specified otherwise in their own 
descriptions. This description of format and args applies to all 
scanf () functions. 

The first argument to scanf () is format, a character string telling 
scanf how to format the data it reads, format consists of text and 
conversion specifications, just as in printf (). The conversion 
specifications tell scanf () how to format the data that is being read in. 
Each conversion specification is matched to a field of input. Depending 
on the conversion specification, that field of input is either fixed length or 
goes until the next white space character in the input string. 

Ordinary text in format is a place-holder which is matched against the 
input text between input Fields. If the input text does not match the text in 
format, the scanf () is aborted. Format syntax and the conversion 
specifications are described below. 

The remaining arguments to scanf are args, a variable number of 
pointers to variables. There should be one arg for each conversion 
specification in format (except for the conversion specifications %* and 
%%, which are explained below). 
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CAUTION : The most common mistake when using scanf () is to use the 
variables themselves rather than the pointers to the variables, scanf () 
needs to know the address of the variables it will use to store data, not 
their present values. Failing to use addresses to store the values will 
overwrite random memory. See the examples. If scanf () runs out of 
arguments before reaching the end of s, arbitrary values from the stack 
are used as the address of the arguments and overwrite random memory. 

White space characters in format are ignored. White space characters are 
spaces, tabs, or newlines. Include them to make the format string more 
readable. White space characters in the input stream separate input fields. 

Non-white space characters (except for %) are matched to the input 
characters. They must match perfectly or else the scanf () is aborted. 

% indicates the start of a conversion specification. 

Conversion specifications begin with % and contain in order: 

% [ * ] [width] [size] 

Assignment Suppression (optional): 

If the first character in the conversion specification is an asterisk (*), 
scanf () reads the input field until the next white space character. It 
does not assign the input field to any variable. 

Field Width (optional): 

n where n is an integer, scanf reads up to n characters for this 

field. If the field is longer than n characters, it skips the rest of the 
field, and continues with the next part of format at the next 
white space in the input. 

Size Specifications (optional): 

1 arg variable for this field is a long. 

h arg variable for this field is a half-word (a short). 

Conversion Characters (terminate conversion specification): 
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c interpret input as a single character; arg should be a char*; 

white space characters are not skipped in this case. %ls will read 
in the next non-white space character. 

d interpret input as a decimal integer; arg should be an int*. 

e,E,f,g,G interpret input as a signed decimal floating point 

number. These operations are all identical. 

o interpret input as an octal integer; arg should be an int*; input 

need not start with 0. 

s interpret argument as a character string; arg should be a char*; 

a ' \0 ' will be added to arg after the string is read in. 

u interpret input as unsigned decimal; arg should be an int*. 

x,X interpret input as a hexadecimal value; arg should be an int*; 
input need not start with Ox. These two specifiers are identical. 

[ scan the input for the set of characters in the format string 

following the [ up to a terminating ] . You can think of the 
characters enclosed in the brackets as a "scanset." scant () will 
take as input the maximum string of characters that match the 
scanset. 

When a circumflex (*) appears as the first character in the scanset 
(e.g. [^0123456789]), it acts as a complement operator, and 
causes all characters not in the set to be matched. 

A range of consecutive characters can be represented by 
separating the first and last members of the range with a hyphen 
(for example [A-Za-z ] will match any alphabetic characters, or 
[ 0 - 9 ] will match the set of digits. If the first character in a range 
is not lexically smaller than the last, then the characters in the 
scanset stand for themselves. For example, [9-1] will match 
the three characters " 9 -1. ” 

To include a right bracket (]) in the scanset, it must be the first 
character in the set For example, [ ] ] will match a single right 
bracket. 
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EXAMPLES 


RETURN VALUE 
SEE ALSO 


arg should be a char [] * large enough to hold the data and the 
terminating ' \ 0 ', which will be added automatically. 

% input should be the character %; input not stored in a variable in 

arg. No arg is used in the process. 


int n; 

scant ("%d ”, &n) ; 

/* correct: &n is a pointer to n */ 
scant(”%d ", n); 

/* incorrect: n is the variable itself, so this will 
trash random memory */ 

Number of items successfully input. 

cscanf (), f scant (), sscanf (), get char (), gets () 
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SEE ALSO 


• SET CONSOLE SCREEN TO ECHO KEYBOARD INPUT 

Set_Echo 

stdio 

#include <stdio.h> 
void Set_Echo(int state); 

Set_Echo () sets the console to echo input from the keyboard to the 
screen. If state is nonzero, then echo is enabled; if state is zero, echo 
is disabled. 

Echo is enabled by default. 

Set_Tab(), getch(), getche() 
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DESCRIPTION 


• SET THE CURRENT STDIO WINDOW 

setwindow 

stdio 

#include <stdio.h> 

void setwindow(FILE *windowFileVar); 

The specified FILE variable becomes the "current” window. The functions 
Set_Echo, Set_Tab, gotoxy, getxpos, getypos, and wputs 
implicitly apply to the current window. 

(Functions which implicitly apply to stdout, such as print f, or to the 
console, such as cprintf, are not affected by which window is current.) 

Initially, stdout is the current window, fopenw does not make the new 
window the current window. 
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SEE ALSO 


• SET TAB WIDTH OF CONSOLE SCREEN 

Set_Tab 

stdio 

#include <stdio.h> 

void Set_Tab(int tab_width); 

Set_Tab() sets the space between tabs on the console screen to 
tab_width. Set_Tab () does not change the internal representation of 
a tab, only the effect of outputting a tab on the console. 

If tab_width is less that 1, it is set to 1. 

Set_Echo () 
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LIBRARY 

SYNTAX 

DESCRIPTION 


RETURN VALUE 

SEE ALSO 


• FORMAT AND MAKE OUTPUT INTO A STRING 

sprintf 

stdio 

#include <stdio.h> 

int sprintf (char *s, char *format, ...) ; 

sprintf () is yet another function based on print f () . Just as 
print f () formats text and data into a string of characters and then prints 
it on stdout, sprintf () formats text and data into a character array. 
That character array is left containing a string of output. Therefore, the 
primary action ofsprintfO is a side effect: changing the contents of 
string s. 

The first argument, s, is a pointer to a character array large enough to 
hold the anticipated result, format and the optional args are 
interpreted in the usual way by print f () (see printf () for details) 
with the result put in s. 

sscanf () is the inverse of sprintf (). It scans and formats input from 
a string. 

Care must be taken to ensure that the buffer pointed to by s is large 
enough to hold the converted string. Also note that the string will be null- 
terminated automatically by sprintf. 

The number of characters put into the buffer pointed to by s, including 
null terminator, if successful; EOF if an error occurs. 

printf (), sscanf () 


60 



stdio 


2 


LIBRARY 

SYNTAX 

DESCRIPTION 


RETURN VALUE 
SEE ALSO 


• SCAN AND FORMAT INPUT FROM A STRING 

sscanf 

stdio 

#include <stdio.h> 

int sscanf (char *s, char *format, ...) ; 

sscanf (), like the other scanf () functions (scanf (), cscanf (), 
and f scanf ()), does a scan and format of a series of characters. The 
special feature of sscanf () is that it takes that series of characters from 
its first argument, a string s. s should terminate in a null ( ' \0 ') 
character format and args are interpreted as usual; see scanf () for 
details. Similarly, sprintf () does a format and print to a character array 
in memory. 

CAUTION : The most common mistake when using sscanf () is to use 
the variables themselves rather than the pointers to the variables, 
sscanf () needs to know the address of the variables it will use to store 
data, not their present values. Failing to use addresses to store the values 
will overwrite random memory. See the examples in s c a n f () . If 
sscanf () runs out of arguments before reaching the end of s, arbitrary 
values from the stack are used as the address of the arguments and 
overwrite random memory. 

Number of items successfully input. 

scanf (), fscanf (), cscanf(), sprintf () 
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• HANDLE EVENT IN A STDIO WINDOW 

StdEvent 

stdio 

#include <stdio.h> 

Boolean StdEvent(EventRecord *theEvent); 

Passed a pointer to an event record, this procedure determines if the event 
relates to one of the windows created with fopenw. If so, it handles the 
event and returns TRUE; otherwise it returns FALSE. If your application 
has its own event loop, you should call StdEvent after calling 
GetNextEvent, and handle the event yourself only if StdEvent returns 
FALSE. 

TRUE if event relates to stdio window, FALSE otherwise. 
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• CONFIGURE FONT FOR STDIO 

Stdio_config 

stdio 

#include <stdio.h> 

void Stdio_config(int font, int size, int style, int 
mode); 

Stdio_config () configures standard I/O to handle Macintosh font 
information. If you want to change the default I/O configuration, you 
must call this function before doing any screen I/O. 

font is the number of a Macintosh font, size is the point size, style is 
the font style (e.g., bold, underscore, etc.), mode is the transfer mode 
(srcCopy, srcOR, etc.). 

See FontMgr.h for symbolic definitions of font names. See 
QuickDraw. h for symbolic definitions of style and transfer mode. 

The default values if Stdio_conf ig () is not called are monaco, 9, 
0, 1, which corresponds to Monaco font, 9 point, normal style, source 
bits ORed. 
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• INHIBIT STDIO INITIALIZATION 

Stdio_MacInit 

stdio 

#include <stdio.h> 

void Stdio_MacInit(Boolean flag);; 

To prevent stdio functions from calling InitGraf, InitFonts, InitWindows, 
InitDialogs, TEInit, and InitMenus, and from setting up the stdio menus, 
etc., call this function with the argument TRUE prior to any stdio calls. 
This will allow you to use stdio windows without conflicting with your 
application's own windows and menus. 
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• GET VERSION OF STDIO LIBRARY 

std_ver 


LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 


stdio 

#include <stdio.h> 
char *std_ver(void) 

This returns a pointer to a string containing the version specification of the 
stdio library. This string is currently "LightspeedC™ Libraries 1.57". 

String representation of stdio library version. 
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• CONVERT A HEXADECIMAL CHARACTER INTO AN INTEGER 

toint 

stdio 

#include <stdio.h> 
int toint(char c) ; 

toint () returns the integer corresponding to the hexadecimal value of a 
character c. For example, toint ( ' 2 ' ) returns the int 2, 
toint ('a') returns the int 10, toint (' F ' ) returns the int 15, 
toint (' r' ) returns -1 to indicate an error, toint () accepts upper or 
lower case. Note that toint () is not the same as atoi () which 
converts a whole string into an int (as opposed to a character), nor is it 
the inverse of toascii (). 

-1 if error; the int that corresponds to the argument if success, 
toascii (),atoi() 
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• CONVERT A CHARACTER TO LOWER CASE 

tolower 

tolower 


LIBRARY 

SYNTAX 


DESCRIPTION 


RETURN VALUE 

SEE ALSO 


stdio 

#include <stdio.h> 
int tolower(char c); 

int _tolower(char c); 

tolower () returns the lower case equivalent of an upper case letter c. 
If c is not an upper case letter, then c is returned unchanged. 

_to lower () is faster. However it returns a wrong value if its argument 
is not an upper case letter. 

The lower case equivalent of upper case character C, or if c is not an 
upper case letter, c itself. 

toupper(), _toupper() 
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• CONVERT A CHARACTER TO UPPER CASE 

toupper 

_toupper 

stdio 

#include <stdio.h> 
int toupper(char c) ; 

int _toupper(char c) ; 

toupper () returns the upper case equivalent of a lower case letter c. If 
c is not a lower case letter, toupper () returns it unchanged. 

_toupper () is faster. However, it returns a wrong value if its argument 
is not a lower case letter. 

The upper case equivalent of lower case letter c; if c is not a lower case 
letter, c itself. 

tolower() 
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SEE ALSO 


• RETURN CHARACTER C TO INPUT STREAM BUFFER 

ungetc 

stdio 

#include <stdio.h> 

int ungetc(int c, FILE *stream) ; 

ungetc () pushes a single character c back to the I/O stream. The next 
read from that stream will get that character first. 

ungetc (s), where s is an input stream from the keyboard, works by 
manipulating the look_full and look_ahead fields of the file 
descriptor (see FILE). When s is a file, the character is placed back into 
the buffer. If the character is different from the last character read and the 
buffer has been modified by a write, the new character will be written to 
the file. 

c if successful; EOF if not. Pushing back EOF places the value of EOF on 
the st ream and returns the value of EOF. 

getc () 


69 



Standard Libraries Reference 


LIBRARY 

SYNTAX 

DESCRIPTION 
RETURN VALUE 
SEE ALSO 


• PUSH CHARACTER BACK TO KEYBOARD INPUT STREAM 

ungetch 

stdio 

#include <stdio.h> 
char ungetch(char c); 

ungetch () pushes the character c back to the keyboard input stream. 
The character c, if the character could be pushed back; otherwise, EOF. 
getch(), ungetc() 
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SEE ALSO 


• VARIABLE FORMAT AND PRINT TO STDOUT 

vprlntf 

vcprintf 

vfprlntf 

vsprintf 

stdio 

#include <stdio.h> 

int vprintf(char *format, char *array); 

int vcprintf(char *format, char *array); 

int vfprintf(char *format, char *array); 

int vsprintf(char *format, char *array)y; 

The vprintf family of routines is entirely analogous in function to the 
similarly named routines lacking the v prefix. That is, vprintf performs 
the same function as printf, vfprintf as fprintf, and so on. 

The difference between each pair of routines is that instead of an 
argument list corresponding to the format specifiers in format, the 
vprintf functions take a single array of arguments. 

In building this array, you must be sure that each item in it corresponds to 
the appropriate format specifier in format. 

The number of characters written, not counting the terminating null 
character (' \ 0 '). 

printf (), cprintf (), fprintf (), sprintf () 
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• WRITE A STRING INTO THE CURRENT STDIO WINDOW 

wputs 

stdio 

#include <stdio.h> 
void wputs(char *s) ; 

This is the same as cputs, but output goes to the current window rather 
than to the console window. 

setwindow 
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Introduction 

The strings library provides routines to copy, concatenate, and scan strings. All of the 
routines in this library operate on null terminated C strings. If you need to use these routines 
on Pascal strings, you can use the CtoPstrO and PtoCstrO routines which are a part of the 
MacTraps library. These are their prototypes: 


char *CtoPstr(char *s) ; 
char *PtoCstr(char *s) ; 

Both of these routines convert the string in place and return a pointer the converted string. 
Since Pascal strings begin with a length byte, they can be no longer than 255 characters. 

If you have the MacHeaders option turned off, be sure to include the file pascal. h . 
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EXAMPLES 

RETURN VALUE 

SEE ALSO 


• COPY FIRST N CHARACTERS FROM S2 TO S1 

stccpy 

strings 

#include <strings.h> 

int stccpy(char *sl, char *s2, int n); 

stccpy () copies n characters from s2 to si. stccpy () will also stop if 
it copies a null character (’NO*) from s2 to si. The area pointed to by s 1 
must be large enough to hold n characters. A ' \ 0 ' is appended to s 1 only 
if less than n characters could be copied from s2 before reaching the end of 
s2. 


The character pointers are incremented by stccpy (). Therefore, the copy 
will overlap what was copied before if (s2 < si < (s2 + n)) 

If n is negative or 0, stccpy () does not copy any characters and returns 0. 

st rcpy () and st rncpy () also copy one string to another, but with some 
small differences. 

The destination string is always null terminated. 

A = ”ABCD”; B = "EFGHIJ"; 

Stccpy(A,B); /* A = ”EFGH” */ 

The number of characters copied if n is positive (including null terminator). 0 
if n is negative or zero. 

strcpy (),strncpy() 
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RETURN VALUE 
SEE ALSO 


• RETURN POSITION OF FIRST CHARACTER IN S NOT IN SET 

stcis 

strings 

#include <strings.h> 

int stcis(char *s, char *set); 

stcis () returns the position of the first character in string s that is not in 
set. The position of the first character in s is 0, the second character is 
position 1, etc. 

If all characters in s are in set, then stcis () returns the position of the 
null character which terminates string s. In effect, this is the length of the 
string, not counting the null at the end. 

set is implemented as a string, but it is logically used as a group of characters 
with order unimportant. 

strspn () is a synonym for stcis (). 

The position of the first character in s that is not in set. 

strspn(),stcisn(),strcspn(),strpbrk (),strrpbrk() 
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SEE ALSO 


• RETURN POSITION OF FIRST CHARACTER IN S THAT IS IN SET 

stcisn 

strings 

#include <strings.h> 

int stcisn (char *s, char *set); 

stcisn () finds the first character in string s which is a member of string 
set. stcisn () returns an int which is the place of the first letter in s to 
be in the set (see examples). The first character in the string s is in place 0, 
the second is in place 1, etc. 

If no character in s is a member of the set, then stcisn () returns the place 
of the null character which terminates string s. This is also the length of the 
string as returned by strlen ( ) . 

The second argument is called a set for semantic reasons; however, it is 
implemented simply as a string. 

strcspn () is a synonym for stcisn (). 

stcisn("word","aeiou") 

/* returns 1 (the place of the o in word) */ 
stcisn("igloo”,"aeiou”) 

/* returns 0 (the place of the i in igloo) */ 
stcisn("GREEN","aeiou") 

/* returns 5 (the place of the '\0* in GREEN) */ 

The place of the first character in s which is in set, or the place of the null 
which terminates s if no character in s is in set. 

stcis(),strcspn(),stpbrk(),strpbrk() 
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RETURN VALUE 
SEE ALSO 


• RETURN THE LENGTH OF STRING S 

stolen 

strings 

#include <strings.h> 
int stolen(char *s) ; 

stolen () simply returns the number of non-null characters in string s. 

strlen () is a synonym for stolen (). 

stolen("the cat”) /* returns 7 */ 
stolen (””) /* returns 0 */ 

The number of non-null characters in s. 

strlen() 
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• RETURN POINTER TO FIRST BLANK SPACE CHARACTER IN PTR 

stpblk 

strings 

#include <strings.h> 
char *stpblk(char *ptr); 

stpblk () finds the first white space character in ptr. 

stpblk () does not stop at a ' \0 ' character marking the end of the string, 
but will continue on through memory until a white space character is found. 

p where p is a char* to the first whitespace character in ptr. 

isspace() 
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RETURN VALUE 

SEE ALSO 


• RETURN POINTER TO FIRST CHARACTER IN S THAT IS IN SET 

stpbrk 

strings 

#include <strings.h> 

char *stpbrk(char *s, char *set); 

stpbrk () finds the first character in string s that is in set. stpbrk () 
returns a pointer to that first character in s (not to the matched character in 
set). It returns null if no characters match. 

Note that set is implemented as a char*, but it is used logically as a set of 
characters. 

strpbrk () is a synonym for stpbrk (). 

strespn () also finds the first character of a string s in a set, but it returns 
an int which is the position of the character rather than a pointer to the actual 
character, strrpbrk () returns a pointer to the last character in s which 
appears in set. 

A pointer to the first character in s that isinset;NULLifno characters in s 
are in set. 

strpbrk (),strespn (),strrpbrk () 


79 



Standard Libraries Reference 


LIBRARY 

SYNTAX 

DESCRIPTION 


RETURN VALUE 
SEE ALSO 


• RETURN POINTER TO FIRST OCCURRENCE OF C IN S 

stpchr 

strings 

#include <strings.h> 

char *stpchr(char *s, char c); 

stpchr () returns a character pointer to the first occurrence of character c in 
string s. If c is not in s, stpchr () returns NULL, stpchr () will not 
search past the null character (' \ 0 ') which ends string s. If c is equal to 
1 \ 0 *, it is considered to match the ' \ 0 ' which terminates string s and a 
pointer to that position is returned. 

strchr () is a synonym for stpchr (). 

strpos () also finds a character c in a string s, but strpos () returns an 
int which is the position of c in s rather than a pointer to that character. 

strrpos () and strrchr () return the position of the last c in s and a 
pointer to the last c in s, respectively. 

null if c is not in s; otherwise, a pointer to the first occurrence of c in s. 
strpos(),strrpos(),strrchr(),strchr() 
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• COPY S2 INTO Si 

stpcpy 

strings 

#include <strings.h> 

char *stpcpy(char *sl, char *s2) ; 

stpcpy () copies the entire string s2 into si. stpcpy () uses 
(strlen (s2) + 1) as the third argument to strncpy () to ensure that 
s2 is copied in its entirety. 

See strncpy () and strlen () for details of their functions. 

Be sure that the character array pointed to by si is sufficiently large, 
strcpy () is synonymous with stpcpy () . 

A pointer to s 1 . 

strncpy(),stccpy(),strcpy() 
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SEE ALSO 


• APPEND S2 TO Si 

strcat 

strings 

♦include <strings.h> 

char *strcat(char *sl, char *s2); 

strcat () calls strncatO to append the entire string s2 to the string 
pointed toby si. 

strcat () uses (strlen(s2) + 1) as the third argument to 

strncatO to ensure that s2 is appended in its entirety. Be sure that there 
is enough space in the character array after the end of the string s 1 to allow 
s2 to be appended. 

The null character which ended string si is overwritten by the first character 
from s2. 

si with s2 appended to it 
strlen (), strncat () 
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RETURN VALUE 
SEE ALSO 


• RETURN POINTER TO FIRST OCCURRENCE OF C IN S 

strchr 

strings 

#include <strings.h> 

char *strchr(char *s, char c); 

strchr () returns a character pointer to the first occurrence of character c in 
strings. If c is not in s, strchr () returns NULL, strchr () will not 
search past the null character (' \ 0 ') which ends string s. 

If c is equal to * \ 0 ', it is considered to match the ' \ 0 ' which terminates 
string s and a pointer to that position is returned. 

stpchr () is a synonym for strchr (). 

strpos () also finds a character c in a string s, but strpos () returns an 
int which is the position of c in s rather than a pointer to that character. 

strrpos () and strrchr () return the position of the last c in s and a 
pointer to the last c in s respectively. 

null if c is not in s; otherwise, a pointer to first occurrence of c in s. 
strpos (),strrpos(),strrchr(),stpchr() 
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SEE ALSO 


• LEXICALLY COMPARE Si AND S2 

strcmp 

strings 

#include <strings.h> 

int strcmp(char *sl, char *s2); 

strcmp () calls strncmp () to compare the length of si to the length of 
s2. strcmp () uses (strlen(sl) + 1) as the third argument to 

strncmp () to ensure that si is compared to s2 in its entirety. 

Note that if si is a substring of s2, then strcmp () will return a number 
greater than 0 because the last characters compared will be the terminating 
null ('NO') character of si against some character in s2. 

See strncmp () and strlen () for details of their functions. 

stscmp () is a synonym for strcmp (). 

0 if string si is the same as string s2; positive if si > s2; negative if si < 
s2. 

strncmp(), strlen(), stscmp() 


84 



strings 


3 


LIBRARY 

SYNTAX 

DESCRIPTION 


RETURN VALUE 
SEE ALSO 


•COPY S2 INTO Si 

strcpy 

strings 

#include <strings.h> 

char *strcpy(char *sl, char *s2); 

strcpy () calls strncpy () to copy the entire string s2 into si. 
strcpy () uses (strlen(s2) + 1) as the third argument to 
strncpy () to ensure that s2 is copied in its entirety. 

See strncpy () and strlen () for details of their functions. 

Be sure that the character array pointed to by si is large enough to hold the 
whole of s2. 

stpcpy () is a synonym for strcpy (). 

A pointer to si. 

strncpy (),stccpy(), stpcpy() 
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• RETURN POSITION OF FIRST CHARACTER IN S THAT IS IN SET 

strcspn 

strings 

#include <strings.h> 

int strcspn(char *s, char *set); 

strcspn () finds the first character in string s which is a member of string 
set. strcspn () returns an int which is the place of the first letter in s to 
be in the set (see examples). The first character in the string s is in place 0, 
the second is in place 1, etc. 

If no character in s is a member of the set, then strcspn () returns the place 
of the null character which terminates string s. This is also the length of the 
string as returned by strlen (). 

The second argument is called set for semantic reasons, however it is 
implemented simply as a string. 

stcisn () is a synonym for strcspn (). 

strcspn("word", "aeiou") 

/* returns 1 (the place of the o in word) */ 
strcspn("igloo", "aeiou") 

/* returns 0 (the place of the i in igloo) */ 
strcspn("GREEN", "aeiou") 

/* returns 5 (the place of the '\0' in GREEN) */ 

The place of the first character in s which is in set. If no character in s is in 
set, then the return value is the position of the null that terminates s. 

stcis (),stcisn (),strspn (),stpbrk(), strpbrk () 
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SEE ALSO 


• RETURN THE LENGTH OF STRING S 

strlen 

strings 

#include <strings.h> 
int strlen(char *s) ; 

strlen () simply returns the number of non-null characters in string s. 

stolen () is a synonym for strlen (). 

The number of non-null characters in s. 

strlen("the cat") /* returns 7 */ 
strlen ("") /* returns 0 */ 

stolen () 
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• APPEND UP TO N CHARACTERS FROM S2 TO S1 

strncat 

strings 

#include <strings.h> 

char *strncat(char *sl, char *s2, int n); 

strncat () appends s2 to si until it has appended n characters or it has 
reached the end of s2. The characters are added to si starting at the first null 
character (' \ 0 ') of si. That ' \ 0 ' is replaced by the first character of s2. 

If n characters are appended without reaching the end of s2, strncat () 
adds a terminating null character (' \ 0 ' )• 

If n is negative or zero, strncat () returns si unchanged- 

si where si is the first argument with the contents of s2 appended to it. 

strcat () 
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• COMPARE UP TO FIRST N CHARACTERS OF S1 AND S2 

strncmp 

strings 

#include <strings.h> 

int strncmp(char *sl, char *s2, int n); 

strncmp () compares si and s2 up to a limit of n, and returns an integer 
indicating whether si is equal to, less than, or greater than s2. 

st rcmp () follows the same rules except that it compares until it reaches the 
end of one or both strings. 

0 if string si is the same as string s2 in the first n characters; positive if si 
> s 2 in the first n characters; negative if s 2 > s 1 in the first n characters. 

strcmp(),stscmp() 
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• COPY UP TO N CHARACTERS FROM S2 TO S1 

strncpy 

strings 

#include <strings.h> 

char *strncpy(char *sl, char *s2, int n); 

strncpy () copies characters from s2 to si until either n characters have 
been copied or it has reached the null character ('NO') which marks the end 
of s2. If the end of s2 is reached first, (n - strlen (s2) ) null 
characters are appended as padding. No null characters are appended if n 
characters from s2 are added without reaching a 'NO' in s2. 

Thus, to reiterate, the first n characters of s 1 will be written over, either by 
the first n characters from s2, or if s2 ends early, s2 plus enough null 
character padding. 

If n is negative or zero, si is returned unchanged, stccpy () also copies n 
characters from s2 to si. 

stccpy () handles null padding differently, and returns the number of 
characters copied instead of a pointer to si. 

strcpy () copies s2, and nothing but s2, to si. 

A pointer to si. 

stccpy(),strcpy() 
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• RETURN POINTER TO FIRST CHARACTER IN S THAT IS IN SET 

strpbrk 

strings 

#include <strings.h> 

char *strpbrk(char *s, char *set); 

strpbrk () finds the first character in string s that is in set. strpbrk () 
returns a pointer to that first character in s (not to the matched character in 
set). It returns null if no characters match. 

stpbrk () is a synonym for strpbrk (). 

strcspn () also finds the first character of a string s in a set, but it returns 
an int which is the position of the character rather than a pointer to the actual 
character, strrpbrk () returns a pointer to the last character in s which 
appears in set. 

A pointer to the first character in s that is in set; null if no characters in s 
are in set. 

stpbrk (),strcspn(),strrpbrk() 
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• RETURN POSITION OF THE FIRST CHARACTER C IN STRING S 

strpos 

strings 

#include <strings.h> 

int strpos(char *s, char c) ; 

strpos () searches s from beginning to end for the character c. 
strpos () returns the first position of c in s, with the first character in s 
being at position 0. strpos () returns -1 if c is not in s. 

strchr () also finds a character c in a string s, but returns a pointer to the 
first such character. 

strrpos () and strrchr () return the position of the last c and a pointer 
to the last c in s respectively. 

The first position of c in s; -1 if c is not in s or if c is ' \ 0 '. 
strchr (),strrchr(), strrpos() 


92 



strings 


3 


LIBRARY 

SYNTAX 

DESCRIPTION 


RETURN VALUE 
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• RETURN POINTER TO LAST OCCURRENCE OF C IN S 

strrchr 

strings 

#include <strings.h> 

char *strrchr(char *s, char c); 

strrchr () searches string s from beginning to end for character c. 
strrchr () returns a pointer to the last occurrence of c that it finds. 

If c is the null character (' \0 '), strrchr () returns a pointer to the null 
character which terminates s. strrchrO returns null if c is not in s. 
strrpos () also finds the last occurrence of a character c in a string s, but 
returns its position as an integer rather than a pointer to it. 

strpos () and strchr () return the position of the first c and a pointer to 
the first c in s respectively. 

A pointer to the last occurrence of c in s; null if c is not in s. 
strrchr (),strpos(),strchr() 
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• RETURN POINTER TO LAST CHARACTER IN STRING S THAT IS IN 
SET 

strrpbrk 

strings 

#include <strings.h> 

char *strrpbrk(char *s, char *set); 

strrpbrk () finds the last character in s that is in set, and returns a 
pointer to that character. The pointer is to the character in s, not the character 
it matches in set. 

Note that while set is implemented as a character string, the order of 
characters in it does not matter. A lower case character does not match its 
equivalent upper case character. 

st rpbrk () returns the pointer to the first character in s that is in set. 

A character pointer to the last character in s that isinset;NULLifno 
character in s is in set. 

strpbrk(),strspn(),stcis(), stcisn() 
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3 


LIBRARY 

SYNTAX 

DESCRIPTION 


RETURN VALUE 
SEE ALSO 


• RETURN POSITION OF THE LAST CHARACTER C IN STRING S 

strrpos 

strings 

#include <strings.h> 

int strrpos(char *s, char c); 

strrpos () searches string s from beginning to end for character c. 
strrpos () returns the last position of c, with the first character of s being 
at position 0. strrpos ( ) returns -1 if c is not in s. 

If c is the null character (' \0 *), strrpos () returns the position of the 
' \ 0 ' which terminates string s. 

strrchr () also finds a character c within a string s, but returns a pointer to 
the last such character. 

strpos () and st rchr ( ) return the position of the first c in s and a 
pointer to the first c in s respectively. 

The position of the last c in s; -1 if c is not in s. 

strrchr (),strpos(),strchr() 
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LIBRARY 

SYNTAX 

DESCRIPTION 


RETURN VALUE 
SEE ALSO 


•RETURN POSITION OF FIRST CHARACTER IN S NOT IN SET 

strspn 

strings 

#include <strings.h> 

int strspn(char *s, char *set); 

strspn () returns the position of the first character in string s that is not in 
set. The position of the first character in s is 0, the second character is 
position 1, etc. 

If all characters in s are in set, then strspn () returns the position of the 
null character which terminates string s. set is implemented as a string, but 
it is logically used as a set of characters with order unimportant. 

stcis () is a synonym for strspn (). 

The position of the first character in s that is not in set. 

stcis (),stcisn (),strcspn(),strpbrk(), strrpbrk () 
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3 


LIBRARY 

SYNTAX 

DESCRIPTION 


RETURN VALUE 

SEE ALSO 


•LEXICALLY COMPARE Si AND S2 

stscmp 

string 

#include <strings.h> 

int stscmp(char *sl, char *s2); 

stscmp () calls strncmp () to compare the entire length of s 1 to the 
length of s2. stscmp () uses (strlen(sl) + 1) as the third argument 
to strncmp () to ensure that si is compared to s2 in its entirety. 

Note that if si is a substring of s2, then stscmp () will return a number 
greater than 0 because the last characters compared will be the terminating 
null character (' \ 0 ') of si against some character in s2. 

See strncmp () and st rlen () for details of their functions. 

strcmp () is a synonym for stscmp (). 

0 if string s 1 is the same as string s2; positive if s 1 > s2; negative if s 1 < 
s2. 

strncmp(),strlen(),strcmp() 
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4 


Introduction 

The math libraries supplied with THINK C provide standard mathematic calculation routines 
as specified in the Second Edition of The C Programming Language. There are a few things 
you should keep in mind when you use the math libraries with THINK C. 

• The global variable errno is defined in the stdio library. If you’re not using the stdio 
library in your program, you should declare errno as a global variable of type int 
somewhere in your program; the declaration should not be static. 

• The values EDOM and ERANGE are declared as an enums in <math. h>. 

• You should include <math. h> in any source file where you use the math routines to 
ensure that the functions are properly declared. If you don’t, you will get wrong answers, 
and your program may not behave correctly. 

68881 Coprocessor Support 

The math libraries supplied with THINK C come in three variations: Math, MathHybrid, 
and Math881. 

U se Math when you are not using the 68881 code-generation capability of THINK C. 

Use MathHybrid when you are using the 68881 code generation, but you want to use the 
SANE functions built into the Macintosh ROM for maximum precision. The tradeoff for using 
MathHybrid is that you do not derive the full performance benefits from the 68881 code 
generation. 

Use Math881 when you are using the 68881 code generation. The routines in this library 
access the 68881 directly for maximum performance. The tradeoff for using Math881 is that 
the transcendental functions (trigonometric and log/exponential functions) will not be as 
accurate as their SANE counterparts. The benefit for using Math8 81 is that the functions in 
this library are about two hundred times faster than the functions in MathHybrid. 

You can access the math functions by adding the appropriate library to your project file, and 
including <math. h> in source files where you need to access the library functions. 
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Error Checking 

The Math and MathHybrid libraries do standard error checking. The routines in these libraries 
test their input arguments. If the result would be undefined, the global variable er rno is set 
to EDOM and the routines return the largest representable double-precision value. 

Note: In cases where the result would be an infinitely large negative 
number, the result is the largest double-precision value with a negative sign. 

The routines also check their results before they return. If the result is not representable as a 
double-precision number, errno will be set to ERANGE. 

If you want to disable error-checking to increase performance, you undefine the symbol 
_ERRORCHECK_ and recompile the appropriate math library. See the next section for details. 

Preprocessor Symbols 

There are two preprocessor symbols that you should define before including <math . h> in 
your source files. The easiest way to do this is to create a header file to hold these definitions, 
and include it before you include <math . h>. 

The proper syntax for defining these symbols is: 

tdefine _ERRORCHECK_ /* for standard error checking */ 

tdefine _MC68881_ /* if you're using 68881 code generation */ 

Note: If these symbols are not defined, you may get linker errors. 

If _ERRORCHECK_ is defined, the math routines do standard error checking as described 
above). If you forget to define this symbol, you're likely to see the error message: 

undefined: errno (math) 

By default, Math and MathHybrid perform error checking, so_ERRORCHECK_ must be 
defined to use these libraries. 

If_MC68 881_ is defined, the libraries are made aware that you are using THINK C's code- 
generation support for the 68881. This Is Important if you are using MathHybrid or 
Math881. If you’re using the 68881 code generation, be sure to define _MC68 8 8l_. 
Conversely, it is very important that _MC 6 8 8 81_ is undefined if you are not using the math 
coprocessor support provided by the THINK C compiler. 
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math 


LIBRARY 
SYNTAX 
DESCRIPTION 
RETURN VALUE 


•Absolute Value of integer 

abs 

math, MathHybrid, Math881 
int abs(int i); 

abs returns the absolute value of its argument, which is an integer. 
I i I for all i. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 


•Trigonometric Arccosine 

acos 

math, MathHybrid, Math881 
double acos(double x); 

acos returns the inverse cosine of the argument x for x in the range of -1 
to +1. 

cos -1 x in the range 0 to re. If I x I is greater than one, zero is returned 
and errno is set to EDOM. 
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math 


LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 


•Trigonometric Arcsine 

asin 

math, MathHybrid, Math881 
double asin(double x) ; 

asin returns the inverse sine of the argument x for x in the range of -1 to 
+ 1 . 

sin -1 x in the range -tu/ 2 to +te/ 2. If Ixl is greater than one, zero is 
returned and errno is set to EDOM. 
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• Trigonometric arctangent 

atan 


LIBRARY 
SYNTAX 
DESCRIPTION 
RETURN VALUE 


math, MathHybrid, Math881 

double atan(double x) ; 

atan returns the inverse tangent of the argument x. 

tan -1 x in the range -n to +K. 
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math 


•arctangent of a Quotient 

atan2 


LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 


math, MathHybrid, Math881 

double atan2(double y, double x); 

atan2 returns the inverse tangent of y/x, with the same sign as y. If 
both x and y are zero, the result is zero, and errno is set to EDOM. 

tan -1 (y/x) in the range -n to +n. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 


• Round Up to Nearest integer 

ceil 

math, MathHybrid, Math881 
double ceil(double x); 

ceil rounds the argument to the next higher integer; for example, 
ceil(l.l) will be 2, and ceil(4.9) is 5. 

x, rounded up to the next integer. 
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math 


•Trigonometric Cosine 

COS 


LIBRARY 
SYNTAX 
DESCRIPTION 
RETURN VALUE 


math, MathHybrid, Math881 
double cos(double x); 
cos returns the cosine of the argument x. 
cos x. 
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•Hyperbolic Cosine 

cosh 


LIBRARY 
SYNTAX 
DESCRIPTION 
RETURN VALUE 


math, MathHybrid, Math881 
double cosh(double x) ; 

cosh returns the hyperbolic cosine of the argument x. 
cosh x. 
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LIBRARY 
SYNTAX 
DESCRIPTION 
RETURN VALUE 


•Base-E power ofx 

exp 

math, MathHybrid, Math881 
double exp(double x) ; 

exp returns E (the base of natural logarithms) to the Xth power. 

e x . If the argument is so large that the result is not representable as a 
double, the largest possible double is returned and errno is set to 
ERANGE. 
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LIBRARY 
SYNTAX 
DESCRIPTION 
RETURN VALUE 


• Floating-point Absolute Value 

fabs 

math, MathHybrid, Math881 
double fabs(double x); 

fabs returns the absolute value of its floating-point absolute value. 
I x | for all values of x. 


110 




math 


LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 


• Round Down to Nearest integer 

floor 

math, MathHybrid, Math881 
double floor(double x) ; 

floor rounds the argument to the next floor integer; for example, 
floor(l.l) will be 1, and f loor(4.9) is 4. 

x, rounded down to the next integer. 


Ill 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 


• Floating-Point Remainder 

fmod 

math, MathHybrid, Math881 

double fmod(double x, double y); 

fmod computes the remainder of x/y, with the sme sign as x. If y is 
zero, errno is set to EDOM. 

remainder of x/y, or max if y is zero. 
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LIBRARY 
SYNTAX 
DESCRIPTION 
RETURN VALUE 

SEE ALSO 


•Split into Fraction and Exponent 

frexp 

math, MathHybrid, Math881 

double frexp(double x, int *exp); 

f rexp splits x into a mantissa and a power of 2. 

The mantissa of x, in the range of 0.5 to 1. The exponent is stored in 
*exp. If x is zero, the function result and *exp will be zero. 

ldexp (), which is the inverse function of frexp (). 
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LIBRARY 
SYNTAX 
DESCRIPTION 
RETURN VALUE 


•Absolute Value of long 

labs 

math, MathHybrid, Math881 
long labs(long 1); 

labs returns the absolute value of its argument, which is a long integer. 
Ill for all 1. 
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math 


LIBRARY 
SYNTAX 
DESCRIPTION 
RETURN VALUE 
SEE ALSO 


•join Fraction and Exponent 

ldexp 

math, MathHybrid, Math881 
double ldexp(double x, int exp); 
ldexp raises 2 to the exp power and multiplies x 
x • 2 ex P. 

f rexp (), which is the inverse function of ldexp (). 


by the result. 
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LIBRARY 
SYNTAX 
DESCRIPTION 
RETURN VALUE 


•BASE-E logarithm 

log 

math, MathHybrid, Math881 
double log(double x) ; 

1 og returns the natural logarithm of its argument. 

In x for all x greater than zero. If x is zero or negative, errno is 
set to EDOM and the negative of the largest representable double is 
returned. 
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LIBRARY 
SYNTAX 
DESCRIPTION 
RETURN VALUE 


•Base-10 logarithm 

loglO 

math, MathHybrid, Math881 

double loglO(double x); 

loglO returns the natural logarithm of its argument. 

logio x for all x greater than zero. If x is zero or negative, errno 
is set to EDOM and the negative of the largest representable double is 
returned. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 


• Split into Integer and Fraction 

modf 

math, MathHybrid, Math881 

double modf(double x, double *ip); 

modf splits x into integral and fractional parts; both parts carry the same 
sign as x. The integral part is stored in *ip. 

the fractional part of x is returned. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 


•POWER FUNCTION 

pow 

math, MathHybrid, Math881 

double pow(double x, double y); 

pow returns the first argument raised to the power of the second 
argument. 

X y for all x greater than zero. If x is zero and y is less than or equal to 
zero, or if x is negative and y is non-integral, errno will be set to EDOM. 
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LIBRARY 

SYNTAX 

DESCRIPTION 


• Random Integer 

rand 

math, MathHybrid, Math881 
int rand(); 

rand returns a random integer. 
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•Trigonometric Sine 


sin 


LIBRARY 
SYNTAX 
DESCRIPTION 
RETURN VALUE 


math, MathHybrid, Math881 
double sin(double x); 
sin returns the sine of the argument 
sin x. 
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LIBRARY 
SYNTAX 
DESCRIPTION 
RETURN VALUE 


• Hyperbolic Sine 

sinh 

math, MathHybrid, Math881 

double sinh(double x) ; 

sinh returns the hyperbolic sin of the argument x. 

sinh x. 
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LIBRARY 
SYNTAX 
DESCRIPTION 
RETURN VALUE 


•Square Root 

sqrt 

math, MathHybrid, Math881 

double sqrt(double x) ; 

sqrt returns the square root of its argument. 

x for all x greater than or equal to zero. If x is less than zero, errno is set 
to EDOM and zero is returned. 
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LIBRARY 

SYNTAX 

DESCRIPTION 


•Set Up Random Number Generator 

srand 

math, MathHybrid, Math881 

int srand(unsigned int seed); 

srand sets the seed for rand () to "seed". 
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•Trigonometric Tangent 

tan 


LIBRARY 
SYNTAX 
DESCRIPTION 
RETURN VALUE 


math, MathHybrid, Math881 

double tan(double x) ; 

tan returns the cosine of the argument x. 

tan x. If x is an odd multiple of te/ 2, err no will be set to EDOM and the 
return value will be max. 
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LIBRARY 
SYNTAX 
DESCRIPTION 
RETURN VALUE 


• H yperbouc Tangent 

tanh 

math, MathHybrid, Math881 
double tanh(double x) ; 

tanh returns the hyperbolic tangent of the argument x. 
tanh x. 
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5 

Introduction 

The storage library provides high level memory management functions found in most C 
environments. Note that these routines call the Macintosh memory manager directly. 
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LIBRARY 

SYNTAX 

DESCRIPTION 


EXAMPLES 


RETURN VALUE 

SEE ALSO 


•ALLOCATE AND CLEAR A BLOCK OF MEMORY 

calloc 

storage 

#include <storage.h> 

char *calloc(unsigned n, unsigned s); 

calloc () dynamically allocates a block of n*s bytes of memory, and 
clears (zeroes) the block, n is the number of items desired, and s is the 
size of each item. This routine uses the standard Macintosh memory 
manager to perform its function. 

There are a half dozen different functions to dynamically allocate memory. 
See the tables in the introduction to this section for a comparison of the 
functions. 

Use the size of operator to find the size of the item to assure portability 
(see the example). Although the block will be properly aligned, you 
should cast the pointer returned by calloc () so that it is guaranteed to 
be formatted as a pointer to the desired type of item. 

cf ree () or free () deallocates a block of memory that was allocated 
by calloc () . 

typedef struct 
{ 

int day, month, year; 
int hours[24]; 

} date; 

char *calloc(); 
date *newmonth; 

if ( (newmonth = (data *) calloc(31, sizeof(date))) 

!= NULL ) 

{/* do work */ } 

A pointer to the newly allocated block; NULL if insufficient memory is 
available. 
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5 


LIBRARY 

SYNTAX 

DESCRIPTION 


RETURN VALUE 
SEE ALSO 


•FREE A BLOCK OF MEMORY 

cfree 

storage 

#include <storage.h> 
int cfree(char *cp) ; 

cfree () releases a block of memory which was dynamically allocated 
bycallocO ormalloc(). 

The argument, cp, is a pointer to an allocated block cp must have been 
allocated by calloc () or malloc () . If cp was not so allocated, 
anything can happen. There are several other library functions which free 
dynamically allocated memory. A table in the introduction to this section 
matches these deallocating functions to the corresponding allocating 
function(s). 

0 if successful; -1 if an error occurs. 

calloc (), malloc (), free(), rlsmem (),rlsml () 
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LIBRARY 

SYNTAX 

DESCRIPTION 


EXAMPLES 

RETURN VALUE 

SEE ALSO 


• CLEAR AND ALLOCATE A LONG BLOCK OF MEMORY 

clalloc 

storage 

#include <storage.h> 

char *clalloc(unsigned long n,unsigned long s); 

clalloc () is yet another function to dynamically allocate memory. 
clallocO is the same as calloc () except that its arguments are 
longs rather than integers. clallocO differs from mla Hoc () in 
that clallocO clears the block of memory. 

In fact, there are a half dozen different functions to dynamically allocate 
memory. See the tables in the introduction to this section for a comparison 
of the functions. Be sure that both arguments in a call to clalloc () are 
longs; this usually requires casting the result of the sizeof 
operator, as illustrated in the example free () and cfree () free 
memory allocated byclallocO . 

long block_ct; 
char c, *c_ptr; 

c_ptr = clalloc(block_ct, (long) (sizeof (c))); 

A pointer to the newly allocated block; NULL if there is insufficient 
memory. 

calloc (), malloc (), mlalloc (), cfree (), free () 
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5 


LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 
SEE ALSO 


• RELEASE WHOLE BLOCK OF MEMORY 

free 

storage 

#include <storage.h> 
int free(char *cp); 

free () releases a block of memory which was dynamically allocated by 
calloc() , malloc(),clalloc () ormlalloc (). free () 
automatically knows how much memory to free. It just needs cp, the 
pointer to the start of the block, cp must have been a pointer that was 
returned by calloc (), malloc () , clalloc () or mlalloc (). The 
whole block is freed. 

0 if successful; -1 if an error occurs. 

calloc (), malloc (), cfree () 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 
SEE ALSO 


• ALLOCATE A BLOCK OF MEMORY 

malloc 

storage 

#include <storage.h> 
char *malloc(unsigned n); 

malloc () dynamically allocates n bytes of memory. Unlike 
calloc (), it does not clear the block of memory, malloc () returns a 
pointer to the block of memory it has allocated, free () and cf ree () 
free memory allocated by malloc () . 

There are actually several different functions to allocate memory. They 
are described together in the introduction to this section as well as 
separately by name. 

A pointer to the block if success; or NULL if failure, 
free (),cfree (), calloc(), clalloc(), mlalloc () 
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LIBRARY 

SYNTAX 

DESCRIPTION 


RETURN VALUE 
SEE ALSO 


• ALLOCATE A LONG BLOCK OF MEMORY 

mlalloc 

storage 

#include <storage.h> 

char *mlalloc(unsigned long n); 

mlalloc () dynamically allocates n bytes of memory, n is a long, so 
mlalloc () can allocate a long block with one call. Unlike clalloc (), 
mlalloc does not clear that block of memory, mlalloc () returns a 
pointer to the block of memory it has allocated, cfree () and f ree () 
deallocate as they do with malloc () . 

There are actually several different functions to allocate memory. They 
are described together in the introduction to this section as well as 
separately by name. 

A pointer to the block if success; NULL if failure, 
calloc (),clalloc(), malloc(), cfree (),free() 
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6 


Introduction 

The unix library provides some functions found in UNIX environments. Not all of the 
routines are meaningful in the Macintosh environment, but they are included for 
compatibility. 

Note that the set jmp. () and long jmp.() functions are actually in the libary 
set jmp. lib. 
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• EXIT AND CALL SYSTEM DEBUGGER 

abort 


LIBRARY 

SYNTAX 

DESCRIPTION 


SEE ALSO 


unix 

#include <unix.h> 
void abort(void); 

Exits and calls the system debugger if it is loaded. Use exit () if you do 
not want the system debugger to be called. This function does not return 
or close files. 

exitO, _exitQ 


136 




LIBRARY 

SYNTAX 

DESCRIPTION 


RETURN VALUE 
SEE ALSO 


unix 


• CONVERT STRING TO A NUMBER 

atoi 

atol 

atof 

unix 

#include <unix.h> 
int atoi(char *s); 

long atoi(char *s); 

double atof(char *s); 

These functions skip over leading white space (isspace('s) is true) and 
convert the string s to the target type. 

atoi (s) Converts s to an integer. 

atoi (s) Converts s to a long. 

atof (s) Converts s to a floating point number. 

A leading minus sign (-) indicates a negative number. 

The converted value of the string. 

st c_d ( ) , st c_i ( ) , stcd_i(), stch_i (), stci_d(), 
stcu d() 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 

SEE ALSO 


• CONCATENATE STRING WITH PROCESS ID NUMBER 

cgetpid 

unix 

#include <unix.h> 

char *cgetpid(char *str); 

cgetpid () returns the user's string (str) concatenated with the 
process id number expressed as a five digit number with leading zeros. 
For example, if the process id = 1, then 

printf("%s",cgetpid("Process")) 

will print ProcessOOOOl. 

A pointer to a string containing str concatenated with the process id 
as returned by getpid () . 

getpid(), setpid() 
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LIBRARY 

SYNTAX 

DESCRIPTION 

SEE ALSO 


unix 6 


•DRAW A CIRCLE 

circle 

unix 

#include <unix.h> 

void circle (int x, int y, int r); 

circle () draws a circle with center x,y and a radius r. 

The Macintosh coordinate system is defined with 0,0 at the top left of the 
screen, and 512,342 at the bottom right. Coordinates are given in pixels. 
The radius is measured in pixels, as are the center coordinates. 

gotoxy(),label (), line(), move(), point() 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 
SEE ALSO 


• CLOSE FILE NUMBER FN 

close 

unix 

#include <unix.h> 
int close (int fn) ; 

Closes the file whose file descriptor number is f n. The file descriptor 
number is the number returned by open () when the file was last 
opened. 

exit () automatically closes all open files, f close () closes a file when 
given a file descriptor number. 

0 if successful; -1 if an error occurs. 

open(), fclose (), _closeall() 
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LIBRARY 

SYNTAX 

DESCRIPTION 

SEE ALSO 


unix 6 


• DRAW LINE FROM CURSOR TO X,Y 

cont 

unix 

#include <unix.h> 
void cont(int x, int y); 

cont () draws a line from the current screen position to position x,y. 
The Macintosh coordinate system is defined with 0,0 at the top left of the 
screen, and 512,342 at the bottom right. 

circle (),gotoxy(), label(),line(),move (),point() 
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• CREATE A NEW FILE CALLED FILENAME 

creat 

LIBRARY unix 

SYNTAX #include <unix.h> 

int creat(char *filename, int mode); 

DESCRIPTION creat () creates a new file named filename. That file is automatically 

opened in the specified mode. The mode argument is described in full 
under open (). The meaningful values for mode when using creat () 
are: 

Opening flags: 

0_RD0NLY read only 

0_WR0NLY write only 

0_RDWR read/write 

0_APPEND append 

Creation flags: 

0_CREAT create if file doesn't already exist 
0_TRUNC reset length to 0 (truncate) if file exits 
O_EXCL don't create if file exists 

File type flags: 

o_ text text file 

0_BINARY binary file 

OR a mode from "Opening Flags" to a mode from "File Type Flags" to 
create and open a specific file type in a specific way. If the file already 
exists (and 0_EXCL is not set), creat () will delete and recreate it. 

creat () returns a file number which is an index into _£ile, the array of 
file descriptors, and is used in calls to such functions as read(), 
write (), close (), and lseek () . 

RETURN VALUE The file number of the newly created and opened file if successful; EOF if 
error. 
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unix 6 


SEE ALSO 


open (), f open (), FILE, _f ile 
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LIBRARY 

SYNTAX 


EXAMPLES 

RETURN VALUE 
SEE ALSO 


• DISPLAY TIME 

ctime 

unix 

♦include <unix.h> 

char *ctime (unsigned long *clock); 

ctime () returns a pointer to a string representing the time. The output 
is a 26 character string in the following form: 

Sun Sep 16 01:03:52 1973\n\0 

If clock is NULL, the time is taken from the Macintosh's time buffer; 
otherwise the time passed in is used. 

♦include <unix.h> 
unsigned long a; 

time (&a); printf(”%s", ctime(&a)); 
printf ( ,, %s", ctime(NULL)); 

A pointer to a string containing the time. 

time (), localtime () 
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6 


LIBRARY 


•ERASE THE SCREEN 

eraseplot 

unix 


SYNTAX 

DESCRIPTION 


#include <unix.h> 
void eraseplot(void); 

eraseplot () erases (fills with white) the screen. The cursor is left at 
0,0 (the upper left corner of the screen). 
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• LAUNCH A PROGRAM 

execl 

execv 

execle 

execve 


LIBRARY 

SYNTAX 


DESCRIPTION 


RETURN VALUE 


unix 

#include <stdio.h> 
int execl(char *path); 

int execv(char *path, char *argv[]); 

int execle(char *path); 

int execve(char *path, char *argv[], char *envp[]); 

These functions just launch the file name indicated by path. There is no 
support for arguments or environment variables. (Refer to the System V 
Unix manual for a complete explanation.) 

These functions never return. 
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LIBRARY 

SYNTAX 

DESCRIPTION 


SEE ALSO 


• CLOSE FILES AND EXIT 

exit 

_exit 

unix 

#include <unix.h> 
void exit(void); 
void _exit(void); 

exit () calls f close () for each open file and then calls _exit () to 
leave the program and return to the shell. Closing the files includes 
flushing the I/O buffers. 

_exit () assumes that the files are closed and exits the program 
immediately. 

exit () is used more often than _exit () because exit () takes care of 
pending I/O in the buffers while closing the files. 

abort(), fclose () 
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LIBRARY 

SYNTAX 

DESCRIPTION 


RETURN VALUE 
SEE ALSO 


• GET FILE NUMBER WHEN GIVEN FILE DESCRIPTOR 

fileno 

unix 

#include <unix.h> 

int fileno(FILE *stream); 

fileno () returns the file number of stream, where stream is a 
pointer to a file descriptor. The file number is simply the number of the 
file descriptor in the array of open file descriptors (see _file and 
FILE). Some library routines (close (), read (), write (), lseek ()) 
access a file by using the file number, others by using ihe pointer to the 
actual file descriptor. 

Files can be opened using either f open () or open (); £ open () returns 
the pointer to the file descriptor, while open () returns the file number. 
Therefore, you can open a file with f open () (returning the file descriptor 
pointer) and later use fileno () to get the file number and use the 
library functions which use the file number. There is no library function 
to go the other way. Instead use _f ile [ f n] which is the file pointer of 
file number f n. 

The file number of stream, if success; EOF if error. 

_file, FILE, fopen (), open () 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 
SEE ALSO 


• RETURN PROCESS ID NUMBER 

getpid 

unix 

#include <unix.h> 
int getpid(void) ; 

getpid () returns the process id number. This number is initially 1, but 
can be changed using setpid (). 

This routine is provided for UNIX compatibility. It has no real function. 
The process id number, 
setpid () 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 
SEE ALSO 


• RETURN USER ID NUMBER 

getuid 

unix 

#include <unix.h> 
int getuid(void) ; 

getuid () returns the user id number. This number is ^initially 1, but can 
be changed using setuid (). 

This routine is provided for UNIX compatibility. It has no real function. 
The user's id number, 
setuid() 


150 




unix 


6 


LIBRARY 

SYNTAX 

DESCRIPTION 


EXAMPLE 


• RETURN THE NEXT TWO BYTES OF STREAM AS INTEGER 

getw 

unix 

#include <unix.h> 

int getw (FILE *stream); 

getw () returns the next two bytes of stream as an integer. The bytes 
are assumed to be in memory image order (that is, according to the 68000 
convention, with the MSB in the first byte). 

int i,j; 
i=0x!234; 


RETURN VALUE 


fputc(i>>8 & OxOOff, fp); 

/* 

MSB 

*/ 

fputc(i & OxOOff, fp); 

/* 

lsb 

*/ 

fseek(fp, -2L, 1); 

/* 

move 

back 2 bytes */ 

j=getw(fp); 

/* 

i—j 

*/ 

EOF is returned if an error occurs. 





SEE ALSO 


putw() 
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LIBRARY 

SYNTAX 

DESCRIPTION 
RETURN VALUE 


• GENERATE A SIGNAL 

kill 

unix 

#include <stdio.h> 

int kill(int pid, int sig) ; 

This generates a signal. Use getpid to determine the night value for pid. 
0 if successful, -1 otherwise (errno contains the actual error number). 
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DESCRIPTION 

SEE ALSO 


unix 6 


• WRITE STRING AT CURSOR POSITION 

label 


unix 

#include <unix.h> 
void label(char *s) ; 

label () writes the null-terminated string s at the current cursor 
position. 

The Macintosh coordinate system is defined with 0,0 at the top left of the 
screen, and 512,342 at the bottom right. Coordinates are given in pixels. 

circle(), gotoxy(), line(), move(), point () 
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LIBRARY 

SYNTAX 

DESCRIPTION 

SEE ALSO 


• PLOT LINE FROM Xl ,Yl TO X2,Y2 

line 

unix 

#include <unix.h> 

void line(int xl, int yl, int x2, int y2); 

line ( ) draws a line from pixel (xl,yl) to pixel (x2,y2) using 
Macintosh QuickDraw calls. 

The Macintosh coordinate system is defined with 0,0 at the top left of the 
screen, and 512,342 at the bottom right. Coordinates are given in pixels. 

circle(), gotoxy(), label(), move(), point () 
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LIBRARY 

SYNTAX 

DESCRIPTION 


RET13RN VALUE 
SEE ALSO 


• RETURN POINTER TO TIME RECORD 

localtime 

unix 

#include <unix.h> 

tm *localtime(unsigned long clock); 

local time () returns a pointer to a UNIX-compatible time record called 
tm. 


The record is of the following form (defined in unix. h): 


typedef struct! 


int 

tm_sec; 

/* 

seconds 0-59 */ 

int 

tm min; 

/* 

minutes 0-59 */ 

int 

tm_hour; 

/* 

hours 0-23 */ 

int 

tm mday; 

/* 

day of month (1-31) */ 

int 

tm mon; 

/* 

month of year (0-11) */ 

int 

tm_year; 

/* 

year -1900 */ 

int 

tm_wday; 

/* 

day of week (sunday=0) */ 

int 

tm_jyday ; 

/* 

day of year (0-365) */ 

int 

tm_isdst; 

/* 

daylight savings time 

} tm; 


NOT 

SUPPORTED! */ 


A pointer to tm. 
time (), ctime () 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 


• LONG OUTPUT CONVERSION 

locv 

unix 

#include <unix.h> 

char *locv(int hi, int lo) ; 

locv () returns a signed double-precision integer Gong), passed as two 
int arguments, to an ASCII string containing a decimal representation of 
that number. The value of the signed double-precision integer is 0ii«l6) 
I lo. 

This function is provided for UNIX compatibility. 

A pointer to a buffer containing the converted null terminated decimal 
string. 

NOTE : Since locv returns a pointer to a static buffer it cannot be used 
more than once in an expression because the second call will overwrite 
the contents of the buffer. 
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RETURN VALUE 
SEE ALSO 
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• MOVE TO A DIFFERENT POINT INSIDE A FILE 

lseek 

unix 

#include <unix.h> 

long lseek(int fn, long offset, int type); 

lseek () allows for non-sequential I/O to a stream. When a file is 
opened for reading or writing, a "logical cursor" is placed at the beginning 
of the file. That logical cursor is marched forward through the file with 
each read or write, lseek () and its cousin f seek () move that logical 
cursor. fseek() is a standard C library function whereas lseek () is the 
UNIX version, (f seek () differs in two main ways: it takes a pointer to a 
file descriptor rather than a file number and it returns an int rather than 
a long.) 

The type argument determines where the seek begins: 

0 offset relative to the beginning of the file 

1 offset relative to current file position 

2 offset relative to the end of file 

offset is simply the count in bytes from the starting point chosen by 
the type argument. 

CAUTION : offset is a long, and can be either positive or negative. 

EOF if error; position in file if success 
fseek () 
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• MOVE CURSOR TO X,Y 

move 


LIBRARY 


unix 


SYNTAX 

DESCRIPTION 


SEE ALSO 


#include <unix.h> 
void move (int x, int y); 

move () moves the cursor to Macintosh pixel position x, r y. 

The Macintosh coordinate system is defined with 0,0 at the top left of the 
screen, and 512,342 at the bottom right. Coordinates are given in pixels. 

circle(), gotoxy(),label(), line(),point () 
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• MOVE N BYTES FROM ONE POSITION TO ANOTHER 

movmem 


LIBRARY 

SYNTAX 

DESCRIPTION 


EXAMPLES 


SEE ALSO 


unix 

♦include <unix.h> 

void movmem(char *s, char *d, unsigned n); 

movmem () copies n bytes from location s in memory to location d. 
This is a block copy operation. The routine checks the relative positions 
of the source and destination to ensure that data is not overwritten during 
the move. 

char sllOOl; 
char t[2001; 

movmem(&tI100] f s, sizeof(s)); 

/• copies last 100 elements of t into s V 

repmem (), setmem () 
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LIBRARY 

SYNTAX 

DESCRIPTION 


RETURN VALUE 
SEE ALSO 


• OPEN FILENAME 

open 

unix 

#include <unix.h> 

int open(char ^filename, int mode); 

open () opens a filename for reading or writing, according to mode, 
open () returns the file number of the open file. That file number is used 
by the library functions read (), write (), lseek () , and close () . 
mode is made by adding together one flag from each of the three groups 
below. 

Opening flags: 

0_RD0NLY read only 

0_WR0NLY write only 

0_RDWR read/write 
0_APPEND append 

Creation flags: 

0_CREAT create if file doesn't already exist 
0_TRUNC reset length to 0 (truncate) if file exits 
0_EXCL don't create if file exists 

File type flags: 

0_TEXT text file 
0_BINARY binary file 

f open () also opens a file, but uses different arguments and returns a file 
pointer rather than a file number. 

creat () uses the opening flags and file type flags described here when 
creating a file. The creation flags are defaulted by creat () to 0_CREAT 
and 0_TRUNC. 

n, where n is the file number of the file (0-14), if success; EOF if error, 
close (),creat (),read(), write(), lseek(), fopen() 
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SYNTAX 

DESCRIPTION 

RETURN VALUE 
SEE ALSO 


unix 


• PRINT USER'S STRING AND ERROR NUMBER 

perror 

unix 

#include <unix.h> 
void perror(char *str); 

perror () prints out the user's string (str) on stdout and then 
"Error number n" where n is the last error number that occurred. 

void 

exit () 
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LIBRARY 

SYNTAX 

DESCRIPTION 

SEE ALSO 


• PLACE A POINT AT LOCATION X, Y 

point 

unix 

#include <unix.h> 

void point(int x, int y); 

point (x,y) sets pixel (x,y) on the Macintosh screen to black. The 
Macintosh coordinate system is defined with 0,0 at the top left of the 
screen, and 512,342 at the bottom right. 

Note: do not confuse this function with the QuickDraw type Point. 
circle(),gotoxy(), label(), line(), move() 
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I • WRITE WORD AS 2 BYTE NUMBER TO STREAM 

putw 

LIBRARY unix 

SYNTAX #include <unix.h> 

int putw(int word, FILE *stream); 

DESCRIPTION putw () writes word as high byte, then low byte to the given output 

stream. Words written to a file are in memory image format. 

RETURN VALUE The word if success; EOF if error. 

SEE ALSO getw () 
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LIBRARY 

SYNTAX 


DESCRIPTION 


SEE ALSO 


• SORT A TABLE IN PLACE 

qksort 

unix 

#include <unix.h> 

void qksort(int nel, int (*compare)(), 
int (*swap)(); 

qksort is an implementation of the quicksort algorithm. It sorts a table 
of data. 

nel is the number of elements in the table. 

compare is the name of a user-supplied comparison function. 

swap is the name of a user-supplied swap function. 

int compare(int i, int j); 

The compare function is passed two indices, starting at zero, into the 
table, the location of which is assumed to be known by compare, 
compare should return an integer less than, equal to, or greater than 
zero, depending on whether the first indexed item is less than, equal to, or 
greater than the second. 

void swap(int i, int j); 

The swap function is passed two indices, starting at zero, into the table, 
the location of which is assumed to be known by swap, swap should 
interchange the two table items. 

qsort () 
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LIBRARY 

SYNTAX 


DESCRIPTION 


SEE ALSO 


• Sort a table in place 

qsort 

unix 

#include <unix.h> 

int qsort(char *base, int nel, int size, 
int (^compare) () ) ; 

qsort is an implementation of the quicksort algorithm. It sorts a table of 
data. 

base points to the first byte of the table, 
nel is the number of elements in the table. 

size is the size of each element in the table. NOTE: to provide an 
efficient implementation for the internal swap procedure, it is assumed 
that if size is 2 or 4, then the table pointed to by base is aligned on a 
word boundary. If it is not, qsort will cause an address error. 

compare is the name of a user-supplied comparison function. 

int compare (type *pl, type *p2) ; 

The compare function is passed two pointers to items of type. 
compare should return an integer less than, equal to, or greater than 
zero, depending on whether the first argument is less than, equal to, or 
greater than the second. 

qksort() 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 
SEE ALSO 


• READ CHARACTERS FROM A FILE 

read 

unix 

#include <unix.h> 

int read(int fn, char *buffer, unsigned int count); 

read () tries to read count bytes from file number f n into the array 
pointed to by buffer. IfreadO reaches the EOF before it has read 
count bytes, it stops and returns the number of bytes it did read. Make 
sure the buffer is large enough to hold the data. An efficient size for 
reading is BUFSIZ, the size of the I/O buffers, f read () also reads data in 
from a file but uses different arguments, including accessing the file by its 
file pointer. 

The number of bytes read; EOF if error, 
fread(), write(), open() 
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• REMOVE FILENAME FROM DIRECTORY 

remove 

LIBRARY unix 

SYNTAX #include <unix.h> 

int remove(char ^filename); 

DESCRIPTION remove () deletes the file from the directory in its entirety. It performs 

the same function as unlink in this implementation. 

RETURN VALUE 0 if success; -1 if failure. 

SEE ALSO unlink (), rename (), creat () 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 
SEE ALSO 


• RENAME A FILE 

rename 

unix 

#include <unix.h> 

int rename(char *old, char *new); 

rename () changes the name of a file in the directory from old to new. 
old and new are C-style null terminated strings. 

0 if success; -1 if failure. 

creat(), remove (), rename() 
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SEE ALSO 


unix 6 


• COPY PATTERN INTO MEMORY 

repmem 

unix 

#include <unix.h> 

void repmem(char *s, char *v, int lv, int nv); 

repmem copies the pattern pointed to by v into memory at s, nv times, 
lv is the length of the pattern string v. 

This means that nv * lv bytes are moved into v. 

allmem ( ) , bldmem ( ) , get mem () f movmem(), rl smem ( ) , 
rstmem (), setmem () 
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• ATTACH PRIVATE BUFFER TO FILE 

setbuf 


LIBRARY 

SYNTAX 

DESCRIPTION 


SEE ALSO 


unix 

#include <unix.h> 

void setbuf (FILE *fp, char *buf); 

setbuf () attaches a private buffer to the file whose file pointer is fp. 
The size of the buffer is BUFSIZ. If buf is NULL then this is the same as 
calling setnbf. 

setnbuf() 
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DESCRIPTION 


RETURN VALUE 
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• PERFORM NON-LOCAL GOTO 

setjmp 

longjmp 

unix 

#include <unix.h> 

int setjmp(jmp_buf env); 

void longjmp(jmp_buf env, int val); 

set jmp () is used with longjmp () to provide a non-local goto 
function, useful for dealing with errors and interrupts in low-level 
subroutines. 

setjmp () saves the stack environment in env and returns the value 0. 
longjmp restores the environment saved by the last call to set jmp (). 
Program execution continues as if setjmp had just returned val. 

set jmp () returns 0 unless longjmp () is called with val=0, in which 
case set jmp () returns 1. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

SEE ALSO 


• SET A FILE TO BE UNBUFFERED 

setnbuf 

unix 

#include <unix.h> 
void setnbuf(FILE *fp); 

setnbuf sets a file as unbuffered; that is, it undoes the effect of a 
previous call to setbuf (). 

setbuf() 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 
SEE ALSO 


•SET PROCESS ID 

setpid 

unix 

#include <unix.h> 
int setpid(int val); 

setpid () sets the process id number to val. 

This call is provided solely for UNIX compatibility. It has no real function, 
val, the argument passed in. 
getpid () 
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• SET USER'S ID NUMBER TO VAL 

setuid 


LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 
SEE ALSO 


unix 

#include <unix.h> 
int setuid(int val); 

setuid sets the user's id number to val. 

This routine is provided for UNIX compatibility. It has no real function, 
val, the argument passed in. 
getuid() 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 


• SET A SIGNAL 

signal 

unix 

#include <stdio.h> 

int (*signal(int sig, int (*func) () ) ) () 

Setting the SIGINT signal allows C and . (command-period) to be trapped. 
Setting the SIGTERM signal is just like calling onexit. Other signals can be 
set, but are only generated by explicit calls to kill. Each signal is 
automatically reset to SIG_DFL once invoked. 

Signals set to SIG_IGN are ignored. All signals are initially set to SIG_IGN. 
Signals set to SIG_DFL will cause the program to exit, or will break to the 
debugger if one is present. 

The previous function set for sig. 
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LIBRARY 

SYNTAX 

DESCRIPTION 


• PAUSE SECONDS, THEN CONTINUE 

sleep 

unix 

#include <unix.h> 
void sleep(int secs); 

sleep () waits secs and then continues. 
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SYNTAX 

DESCRIPTION 

RETURN VALUE 
SEE ALSO 
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• CONVERT AN ASCII INTEGER VALUE TO AN INTEGER 

stcd_i 

unix 

#include <unix.h> 

int stcd_i(char *s, int *r) ; 

stcd_i () converts an ASCII string s to an integer. The result is placed 
in r and the number of characters scanned is returned. Scanning stops 
when an invalid character is present. Valid characters are 0-9, —, and +. 

stcd_i () is similar to atoi (). 

The number of characters scanned. 

stch_i(), stci_d(), stcu_d() , atoi() 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 
SEE ALSO 


• CONVERT AN ASCII HEX VALUE TO AN INTEGER 

stch_i 

unix 

#include <unix.h> 

int stch_i (char *s, int *r) ; 

s t c h_i () converts an ASCII hex string s to an integer. The result is 
placed in r and the number of characters scanned is returned. Scanning 
stops when an invalid character is present. Valid characters are 0-9, a-f, 
A-F, and +. 

The number of characters scanned. 
stcd_i (), stci_d (), stcu_d () 
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RETURN VALUE 
SEE ALSO 


unix 6 


♦ CONVERT INTEGER TO ASCII STRING, PLACE STRING IN 
BUFFER 

stci_d 

unix 

#include <unix.h> 

int stci_d(char *out, int in, int outlen); 

stci_d () converts the integer in to an ASCII string and places the string 
in the buffer pointed to by out. A maximum of outlen characters are 
placed into the buffer. 

Number of characters placed in buffer out, not including null terminator. 
stch_i (), stcd_i() stcu_d() 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 

SEE ALSO 


• CONVERT INTEGER TO ASCII STRING, PLACE STRING IN 
BUFFER 

stcu_d 

unix 

#include <unix.h> 

int stcu_d(char *out, unsigned in, int outlen); 

st cu_d () converts the unsigned integer in to an ASCII string and places 
the string in the buffer pointed to by out. A maximum of outlen 
characters are placed into the buffer. 

The number of characters placed in buffer out, not including null 
terminator. 

stcd_i (), stch_i(), stci_d() 
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• PARSE FILENAME PATTERN 

stspfp 

unix 

#include <unix.h> 

int stspfp(char *p, int n[ 16 ]); 

stspfp parses a filename pattern which consists of node names 
separated by colons. Each colon is replaced by a null byte and the 
beginning index of that node is placed in the index array. 

For example, : abc : de: f gh has 3 nodes, and their indices are 1 for 
abc, 5 for de and 8 for f gh. The last entry in the array index is -1. 

0 if successful; -1 if too many nodes or other error. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 
SEE ALSO 


• RETURN POSITION WITHIN FILE 

tell 

unix 

#include <unix.h> 
long tell(int fildes); 

tell returns the position within the file. This is the UNIX equivalent to 
f tell, except you pass the file's number instead of the file descriptor. If 
an error occurs then EOF is returned. 

A long representing the position within file if success; EOF if error, 
f tell () 
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♦ RETURN THE TIME IN SECONDS 

time 

LIBRARY unix 

SYNTAX #include <unix.h> 

unsigned long time(unsigned long *tloc); 

DESCRIPTION time () returns the time in seconds since Jan 1, 1970, 00:00:00. If tloc 

is not NULL, then the time is placed in tloc also. 

RETURN VALUE The time in seconds since Jan 1, 1970, 00:00:00. 

SEE ALSO ctime (), localtime () 
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• RETURN TERMINAL ID NUMBER 

ttyn 

LIBRARY unix 

SYNTAX #include <unix.h> 

int ttyn(void) 

DESCRIPTION ttyn () returns the terminal id number, which is 1. This routine is 

provided for UNIX compatibility, and performs no real function. 

RETURN VALUE The terminal id number, which is 1. 

SEE ALSO setpid (), setuid (), getuid (), getpid () 
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• UNLINK A FILE FROM THE DIRECTORY 

unlink 


LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 
SEE ALSO 


unix 

#include <unix.h> 

int unlink(char *filename); 

unlink () removes filename from the directory and deletes the file. The 
library function remove () also removes a file from the directory. 

0 if success; -1 if failure. 

creat(), remove(), rename () 
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LIBRARY 

SYNTAX 

DESCRIPTION 


RETURN VALUE 
SEE ALSO 


• WRITE A BLOCK OF BYTES TO A FILE 

write 

unix 

#include <unix.h> 

int write(int fn, char *buffer, unsigned nbytes); 

write ( ) copies nbytes from buffer to the file with file descriptor 
number fn. The most efficient choice for nbytes is usually BUFSIZ. 

f write () is another library function to write a block of data to a file, 
with some differences, write () uses the file number (returned if 
open () is used to open the file) while f write () uses the file descriptor 
pointer (returned if fopen () is used to open the file). In addition, 
write () has three arguments, while fwrite () has four. Therefore, 
write () and f write ( ) are NOT synonymous. 

The number of bytes copied, if success; -1 if error. 

fwrite () 
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Introduction 

The unix_st rings library provides some string functions found in UNIX environments. 
Some of the routines here have the same functionality as routines in the the strings library. 
They are included for compatibilty.. 
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LIBRARY 

SYNTAX 

DESCRIPTION 


EXAMPLES 


RETURN VALUE 


• COUNT NUMBER OF CHARACTERS IN STRING THAT ARE IN SET 

stcarg 

unix_strings 

#include <strings.h> 

int stcarg(char *s, char *set); 

stcarg () counts the number of characters in string s that are in set. 

stcarg () will ignore strings enclosed in double quotes or literals 
enclosed in quotes inside s (see example). A backslash character in s is 
also ignored. 

Consequently, a single quote, a double quote, or a backslash contained in 

* set will never match a character in s. 

stcarg () returns the count of matched characters. 

stcarg("abcde","12345") /* returns 0 */ 
stcarg("aabcd","aeiou") /* returns 2 */ 

stcarg("aeiou","aabcd") /* returns 1 */ 
stcargC'abcWd", "abc\\d") 

/* returns 4 (the backslash character is ignored) */ 
stcarg(”'s'tp","stp") 

/* returns 2 (the s is ignored because it is quoted) 
*/ 

The number of characters in s that are in set with the restrictions 
described above. 
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• SEARCH FOR PATTERN ANYWHERE IN STRING 

stcpm 

unix_strings 

#include <strings.h> 

int stcpm(char *string, char *pattern f char *q); 

stcpm () calls stcpma () repetitively to search for pattern anywhere 
in string. 

stcpm () allows wildcard matches in pattern, using the following 
pattern-matching rules: 

? matches any single character. 

c* (where c can be replaced by any character) matches any number 
of consecutive c characters (including 0). 

c+ (where c can be replaced by any character) matches one or more 
consecutive c characters (but not 0 characters). 

To match a wildcard character literally, precede it by a backslash (\) 
character. For example, \* in pattern will only match a single * in 
string, \ ? will only match a ?, and \+ will only match a + (When you 
are writing the backslash character in a string for the compiler, you have 
to precede the backslash character itself with a backslash. \ \ is turned by 
the compiler into a single backslash character. In input from the keyboard 
or a file, a single backslash is sufficient.). 

Because of wildcards and backslashes, the number of characters matched 
is not necessarily the same in pattern as in string (for example, 
pattern = "ab+cd", string = "abbbbbcd” is a perfect match 
even though pattern has 5 characters and string has 8). 

NOTE : stcpm () returns two values, one directly and one by side effect. 
Its return value is an int which is the length of the matched pattern if a 
match is made, and 0 if no match is made. 

* q, the third argument, is used to return a pointer to the first occurrence 
of pattern in string (or is left unchanged if no match is made). 
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EXAMPLES 


RETURN VALUE 


SEE ALSO 


char *substring; 

stcpm( ,, bxde", ”a*b+?d", &substring) 

/* returns 3 and sets substring to the address of 
the start of the source string Note that a* matches 
zero or more 
instances of ”a”.*/ 


stcpm ("yybxde”, ”a*b+?d”, &substring) 

/* returns 3 and sets substring to the address of 
' b' in the source string.*/ 

0 if pattern is not in string; n where n is the length of pattern if 
pattern is in string; by side effect, the third argument *q is set to p 
where p is a pointer to the first pattern in string. *q is left unchanged if 
no match occurs. 

stcpma () 
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• MATCH PATTERN AT START OF STRING 

stcpma 

unix_strings 

#include <strings.h> 

int stcpma(char *string, char *pattern); 

stcpma () compares pattern to the beginning of string. If they 
match exactly, stcpma () returns the number of characters in the match. 
If they partially match, stcpma () returns the number of characters until 
they differ. If they don't match at all, stcpma () returns 0. 

stcpma () supports the following wildcard matching syntax in pattern: 

? matches any single character. 

c* (where c can be replaced by any character) matches any number 
of consecutive c characters (including 0). 

c+ (where c can be replaced by any character) matches one or more 
consecutive c characters (but not 0 characters). 

To match a wildcard character literally, precede it by a backslash (\) 
character. For example, \* inpattern will only match a single * in 
string, \? will only match a ?, and \+ will only match a + (When you 
are writing the backslash character in a string for the compiler, you have 
to precede the backslash character itself with a backslash. \ \ is turned by 
the compiler into a single backslash character. In input from the keyboard 
or a file, a single backslash is sufficient.). 

Because of wildcards and backslashes, the number of characters matched 
is not necessarily the same in pattern as in string (for example, 
pattern = "ab+cd", string = "abbbbbcd" is a perfect match 
even though pattern has 5 characters and string has 8). The number 
returned is the number of characters in string that were matched. 
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EXAMPLES 

RETURN VALUE 

SEE ALSO 


stcpma("bxde”, "a*b+?d"); 

/* returns 3 */ 

stcpma("yybxde", "a*b+?d"); 

/* returns 0 */ 

The number of characters at the beginning of string that match .br 
pattern; 0 if no characters match. 

stcpm() 
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• PARSE FIRST SYMBOL IN INPUT 

stpsym 

unix_strings 

#include <strings.h> 

char *stpsym(char *input, char *output, int symlen); 

stpsym () finds the first symbol in input. A symbol begins with a letter 
(upper or lower case) and ends at the first character which is not a letter or 
digit, stpsym () copies up to the first (symlen - 1) characters of the 
first symbol from input to output. 

The symlen argument should be the length of output available, as it 
keeps stpsym () from copying too much into output and destroying 
the memory that follows. A null character (' \ 0 ') is added to output 
after the last character from the symbol. 

st rpsym () also returns a pointer to the first character in input after the 
symbol. If the first character in input does not begin a symbol, 
stpsym () does not copy into output and returns a pointer to the first 
character in input. 

Note that if the first symbol in input is larger than (strlen - 1) 
characters, stpsym () returns a pointer to the next character in that 
symbol as the beginning of the next symbol. Thus, if the character at the 
return pointer is a letter or digit, you know that the preceding symbol has 
been broken in two. 

The key thing to remember is that stpsym () returns two things: a copy 
of the symbol in output and a pointer to the character after the symbol 
in input. 

stpsym(" abc_l ", sym, sizeof(sym)) 

/* sets sym = "abc" */ 
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RETURN VALUE 


SEE ALSO 


Directly: p where p is a pointer into string to the character after the 
symbol, p points to the beginning of s if it does not begin a symbol. 

By side effect, output has a copy of the first symbol from string (up to 
(strlen - 1) characters) terminated with a 'NO*. 

stptok() 
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• PARSE FIRST TOKEN IN INPUT 

stptok 

unix_strings 

#include <strings.h> 

char *stptok (char *input, char *output, int toklen, 
char *brkset); 

stptok ( ) parses the next token in input. A token is defined as a 
sequence of characters not containing any characters from brkset, the 
fourth argument to stptok (). 

stptok () has two effects. First, stptok () copies up to the first 
(toklen - 1) characters from the first token in input to output and 
appends a null character (' \ 0 ') to output. Second, stptok () returns 
a pointer to the first character after the token. 

There are two special cases to be aware of. If the first character in input 
is not part of a token (and therefore a member of the brkset), 
stptok () puts a ' \0 ' at the start of output and returns a pointer to 
that first character in input. If the first token in input is longer than 
(toklen - 1) characters, the pointer returned is & input [toklen] , 
even though that character might seem to be logically part of the first 
token. 

stptok () is parallel to stpsym () in every way. stpsym () parses the 
first symbol (letters and digits) of an input stream. 

stptok("abc to 2", sym, sizeof (sym), "5”) 

/* returns a pointer to the first character 
in the source and sets sym to "abc” */ 

A pointer to the next character in input after the first token is parsed; by 
side effect, output contains a copy of the first (toklen - 1) 

characters of the first token in input, output is always terminated with 
a ' \0 '. 

stpsym () 
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Introduction 

The storageu library provides low level memory management found in Unix 
environments. These routines call the Macintosh memory manager to build a storage pool. 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 
SEE ALSO 


•ALLOCATE LEVEL 2 MEMORY POOL 

allmem 

storageu 

#include <storage.h> 
int allmem(void) ; 

allmem () is equivalent to the call: bldmem (0) . 

Note: The UNIX library procedures getmem (), getml (), rlsmem (), 
rlsml (), allmem(), bldmemO, rbrk (), rstmemO, lsbrk(), 
and sbrk () are not recommended for casual use. These procedures 
attempt to provide low-overhead UNEX-like memory allocation, and are 
provided for compatibility purposes. 

0 if success; -1 if failure. 

bldmem (), rbrk (), rstmem () 
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LIBRARY 

SYNTAX 

DESCRIPTION 


RETURN VALUE 
SEE ALSO 


• SET UP LEVEL 2 MEMORY POOL 

bldmem 

storageu 

#include <storage.h> 
int bldmem(int n) 

bldmem () allocates a pool of n K bytes of memory for subsequent 
getmem () and getml () calls. 

Typically, you would make some initial calls to lsbrk () or sbrk () to 
get "level T memory. Then you would make a call to allmem ( ) or 
bldmem () to set up a level 2 memory pool. 

Memory allocated by getmem () and getml () calls after a call to 
allmem () or bldmem () can all be released by a call to rstmem () . 

Note:.The UNIX library procedures getmem (), getml (), rlsmem (), 
rlsml (), allmem (), bldmem (), rbrk (), rstmem (), lsbrk (), and 
sbrk () are not recommended for casual use. These procedures attempt 
to provide low-overhead UNIX-like memory allocation, and are provided 
for compatibility purposes. 

0 if success; -1 if failure. 

allmem (), rbrk (), rstmem () 
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RETURN VALUE 

SEE ALSO 


• DYNAMICALLY ALLOCATE N BYTES OF MEMORY 

getmem 

storageu 

#include <storage.h> 
char *getmem(unsigned n) 

getmem () gets n bytes of memory from the free memory pool allocated 
by bldmem (). The memory is not automatically zeroed. 

getml () is the same as getmem () except that it can allocate a block of 
memory that can be greater than 65535 bytes. There are actually a half 
dozen different functions which dynamically allocate memory. They are 
described together in the introduction to this section as well as on the 
separate pages describing each function. 

Use r lsmem () to free memory allocated by getmem (). 

Note: The UNIX library procedures getmem (), getml (), rlsmem (), 
rlsml () , allmem(), bldmem(), rbrk (), rstmem (), lsbrk (), and 
sbrk () are not recommended for casual use. These procedures attempt 
to provide low-overhead UNIX-like memory allocation, and are provided 
for compatibility purposes. 

A pointer to the newly allocated block; or NULL if error (such as 
insufficient memory). 

getml (), rlsmem (), rlsml () 
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LIBRARY 

SYNTAX 

DESCRIPTION 


RETURN VALUE 

SEE ALSO 


• DYNAMICALLY ALLOCATE N BYTES OF MEMORY 

getml 

storageu 

#include <storage.h> 

char *getml(unsigned long n); 

getml () gets n bytes of memory from the free memory pool allocated 
by bldmem (). The memory is not automatically zeroed, get mem () is the 
same as getml () except that it can allocate only an integer length block 
of memory. 

There are actually a half dozen different functions which dynamically 
allocate memory. They are described together in the introduction to this 
section as well as separately by name. 

Use rlsml () to free memory allocated by getml (). 

Note: The UNIX library procedures getmem (), getml (), rlsmem (), 
rlsml(), allmem(), bldmem(), rbrk(), rstmem (),lsbrk (),and 
sbrk () are not recommended for casual use. These procedures attempt 
to provide low-overhead UNIX-like memory allocation, and are provided 
for compatibility purposes. 

A pointer to the newly allocated block; or NULL if error (such as 
insufficient memory). 

getmem (), rlsml () 
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LIBRARY 

SYNTAX 

DESCRIPTION 


RETURN VALUE 
SEE ALSO 


• DYNAMICALLY ALLOCATE A BLOCK OF N BYTES 

lsbrk 


storageu 

#include <storage.h> 

char *lsbrk(unsigned long n) 

lsbrk () allocates a long block of bytes. The block is not zeroed. This is 
a low-level UNIX call for getting memory. There are half a dozen different 
ways to allocate memory. They are described together in the introduction 
to this section as well as individually by function name. 

Note: The UNIX library procedures getmem () , getml () , rlsmem () , 
rlsml (), allmem (), bldmem(), rbrk (), rstmem (), lsbrk (), and 
sbrk () are not recommended for casual use. These procedures attempt 
to provide low-overhead UNIX-like memory allocation, and are provided 
for compatibility purposes. 

NULL if error; the pointer to the newly allocated block if success, 
rstmem (), sbrk (), getml (), getmem () 
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DESCRIPTION 

SEE ALSO 


•RESET MEMORY BREAK POINT 

rbrk 

storageu 

#include <storage.h> 
void rbrk(void); 

rbrk () resets the memory break point to the starting position. 

Note: The UNIX library procedures getmem (), getml (), r Is mem () , 
rlsml (), allmem (), bldmem (), rbrk (), rstmem (), lsbrk (), and 
sbrk () are not recommended for casual use. These procedures attempt 
to provide low-overhead UNIX-like memory allocation, and are provided 
for compatibility purposes. 

allmem() , bldmem(), rstmem(), lsbrk(), sbrk() , getmem() , 
rlsmem (), getml (), rlsml (), rstmem () 
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LIBRARY 

SYNTAX 

DESCRIPTION 


RETURN VALUE 
SEE ALSO 


• CHANGE THE SIZE OF AN ALLOCATED REGION OF MEMORY 

realloc 

storageu 

#include <storage.h> 

char *realloc(char *ptr, unsigned int size) 

realloc () changes the size of the memory region pointed to by ptr 
while preserving its contents. 

If the new size is larger than the old, new space is added at the end. If 
necessary, the contents are copied to another region of memory. If the 
new size is smaller than the old, space is taken away at the end of the old 
region and the contents of that portion are lost. 

relallocO can be used if you need a larger size specification (long 
rather than int). 

A pointer to the (new) region in memory if success; NULL if error, 
relalloc() 
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LIBRARY 

SYNTAX 

DESCRIPTION 

RETURN VALUE 
SEE ALSO 


• CHANGE THE SIZE OF AN ALLOCATED REGION OF MEMORY 

relalloc 

storageu 

#include <storage.h> 

char *relalloc(char *ptr, unsigned lonsize) 

relalloc changes the size of the memory region pointed to by ptr 
while preserving its contents. If necessary, the contents are copied to 
another region of memory. 

This function is identical to realloc except that it allows for a larger 
size specification (long rather than int). 

A pointer to the (new) region in memory if success; NULL if error. 

realloc () 
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LIBRARY 

SYNTAX 

DESCRIPTION 


RETURN VALUE 
SEE ALSO 


• RELEASE MEMORY ALLOCATED BY GETMEMO 

rlsmem 

storageu 

#include <storage.h> 

int rlsmem(char *cp, unsigned n) 

rlsmem () releases a block of memory allocated by getmem (). cp is a 
pointer to the first character in the block, and n is an unsigned length of 
the block. 

rlsmem () is analogous to f ree (), which releases a block of memory 
allocated by calloc (). Note the difference between rlsmem () and 
free () : rlsmem () needs to be told how many bytes to release, while 
free() releases the whole block automatically. For that reason, 
rlsmem () is both more flexible (can release part of a block) and more 
difficult to use than f ree (). 

rlsml () releases memory allocated by getml () or getmem (). 

The introduction to this section contains a list matching allocating 
functions with deallocating functions. 

Note: The UNIX library procedures getmem (), getml (), rlsmem (), 
rlsml (), allmem (), bldmem(), rbrk (), rstmem () , lsbrk (), and 
sbrk () are not recommended for casual use. These procedures attempt 
to provide low-overhead UNIX-like memory allocation, and are provided 
for compatibility purposes. 

0 if success; -1 if failure. 

getmem(), rlsml (), getml() 
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LIBRARY 

SYNTAX 

DESCRIPTION 


RETURN VALUE 
SEE ALSO 


• RELEASE MEMORY GOT BY GETMLO 

rlsml 

storageu 

#include <storage.h> 

int rlsml(char *cp, unsigned long n); 

rlsml () releases a block of memory got by get ml () . cp is a pointer to 
the first character in the block, and n is an unsigned length of the block. 

rlsml () is analogous to free () , which releases a block of memory 
allocated by calloc (). Note the difference between rlsml () and 
f ree (): rlsml () needs to be told how many bytes to release, while 
free () releases the whole block automatically. For that reason, 
rlsml () is both more flexible (can release part of a block) and more 
difficult to use than free (). 

rlsmem () releases memory allocated by getmem (). 

The introduction to this section contains a list matching allocating 
functions with deallocating functions. 

Note: The UNIX library procedures getmem (), getml (), rlsmem () , 
rlsml(), allmem(), bldmem(), rbrk(), rstmem (),lsbrk (),and 
sbrk () are not recommended for casual use. These procedures attempt 
to provide low-overhead UNIX-like memory allocation, and are provided 
for compatibility purposes. 

0 if success; -1 if failure. 

getml (), rlsmem () 
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• RESET MEMORY ALLOCATED BY GETMEMO 

rstmem 


LIBRARY 

SYNTAX 

DESCRIPTION 


SEE ALSO 


storageu 

#include <storage.h> 
void rstmem(void) ; 

rstmem () releases the memory allocated by getmem () calls made after 
calls to allmem () or bldmem (). 

Note: The UNIX library procedures getmem (), getml (), rlsmem (), 
rlsml (), allmem (), bldmem (), rbrk (), rstmem () , lsbrk (), and 
sbrk () are not recommended for casual use. These procedures attempt 
to provide low-overhead UNIX-like memory allocation, and are provided 
for compatibility purposes. 

allmem (), bldmem () , rbrk () , sbrk (), lsbrk (), .br getmem (), 
getml (), rlsmem (), rlsml () 
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LIBRARY 

SYNTAX 

DESCRIPTION 


RETURN VALUE 
SEE ALSO 


• DYNAMICALLY ALLOCATE A BLOCK OF N BYTES 

sbrk 

storageu 

#include <storage.h> 
char *sbrk(unsigned n) 

sbrk () dynamically allocates a block of n bytes. The block is not zeroed. 
A similar function, calloc (), allocates a block and zeroes it before 
returning. 

rbrk () is used to release memory allocated by sbrk(), lsbrk(), 
getmem () or getml (). 

Note: The UNIX library procedures getmem (), getml (), rlsmem (), 
rlsml(), allmem(), bldmem(), rbrk(), rstmem (),lsbrk (),and 
sbrk () are not recommended for casual use. These procedures attempt 
to provide low-overhead UNIX-like memory allocation, and are provided 
for compatibility purposes. 

A pointer to the newly allocated block; NULL if error, 
lsbrk (),getmem (),getml () 
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• INITIALIZE A BLOCK OF MEMORY 

setmem 


LIBRARY 

SYNTAX 

DESCRIPTION 

SEE ALSO 


storageu 

#include <unix.h> 

void setmem(char *addr, unsigned n; char c); 

setmem () initializes a block of memory starting at addr, for n bytes, to 
the value c. 

movmem (), repmem () 
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License Agreement 


License Agreement 

This manual and the software described in it were developed and are copyrighted by 
Symantec Corp. (Symantec) and are licensed to you on a non-exclusive, non-transferable 
basis. Neither the manual nor the software may be copied in whole or in part except as 
follows: 

1) You may make backup copies of the software for your use provided that they bear 
Symantec’s copyright notice. 

2) You have the right to include object code derived from the libraries in programs that you 
develop using the software and you also have the right to use, distribute and license such 
programs to third parties without payment of any further license fees, so long as a copy¬ 
right notice sufficient to protect your copyright in the software in the United States or any 
other country is included in the graphic display of your software and on the labels affixed 
to the media on which you software is distributed. 

You may not in any event distribute any of the source files provided or licensed as part of the 
software. You may use the software at any number of locations so long as there is no pos¬ 
sibility of it being used at more than one location at a time. 

Symantec’s Plain Language License Statement 

Symantec is concerned with how you copyright your software only in the case where you 
use object code of libraries which Symantec provides in source form (MacTraps does not fall 
into this category). These libraries may be included in your program so long as a copyright 
notice that will protect your copyright in the software is in the “About box” of your software 
and on the disk labels, as specified in the license agreement. You are not required to include 
a specific Symantec copyright notice except if your copyright does not satisfy the above 
requirement. This is only an explanation of the License Agreement. All terms and conditions 
of the License Agreement apply. 

Limited Warranty on Media and Manuals 

If you discover physical defects in the media on which this software is distributed or in the 
manuals distributed with the software, Symantec will replace the media or manuals at no cost 
to you provided that you return the defective materials along with a copy of your receipt to 
Symantec or to an authorized Symantec dealer during the 60-day period following your re¬ 
ceipt of the software. 

Limited Warranty on the Product 

Symantec warrants that the software will perform substantially as described in the User’s 
Manual. If within 60 days of receiving the software, you give written notification to Symantec 
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of a significant, reproducible error in the software which prevents operation, and provide a 
written description of the possible problem along with a machine readable example, if ap¬ 
propriate, Symantec will either provide you with corrective or workaround instructions, a 
corrected copy of the software, a correction to the User’s Guide and Reference Manual, or 
Symantec will refund your purchase price upon return of all copies of the software and doc¬ 
umentation together will a copy of your receipt. This warranty extends only to you and shall 
be void if the software has been tampered with, modified, or improperly used, or if the soft¬ 
ware is used on hardware other than the Apple Macintosh™ Computer. 

EXCEPT FOR THE LIMITED WARRANTY DESCRIBED ABOVE, THERE ARE NO WAR¬ 
RANTIES TO YOU OR ANY OTHER PERSON OR ENTITY FOR THE PRODUCT EXPRESSED 
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OR MER- 
CHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. ALL SUCH WARRANTIES ARE 
EXPRESSLY AND SPECIFICALLY DISCLAIMED. Some states do not allow the exclusion of 
implied warranties or limitations on how long they last, and you also may have other rights 
that vary from state to state. IN NO EVENT SHALL SYMANTEC BE RESPONSIBLE FOR ANY 
INDIRECT, SPECIAL, INCIDENTAL, CONSEQUENTIAL, OR SIMILAR DAMAGES OR LOST 
DATA OR PROFITS TO YOU OR ANY OTHER PERSON OR ENTITY REGARDLESS OF THE 
LEGAL THEORY, EVEN IF WE HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH 
DAMAGE. Some states do not allow the exclusion or limitation of incidental or consequential 
damages, so the above limitation or exclusion may not apply to you. The warranty and 
remedies set forth are exclusive and in lieu of all others, oral or written, express or implied. 

SYMANTEC MAKES NO WARRANTY OF THE PERFORMANCE OF THE LIBRARIES WHEN 
USED IN YOUR SOFTWARE. YOU AGREE TO INDEMNIFY SYMANTEC FROM ALL CLAIMS 
BY THIRD PARTIES ARISING IN CONNECTION WITH THE USE OF YOUR SOFTWARE. 

General Terms This license states the entire agreement between the parties and supercedes 
all other communications between the parties relating to this License, which shall be gov¬ 
erned and construed in accordance with the laws of the State of California. You agree to 
bring any proceeding to enforce or construe this License or involving the performance of the 
software only in a federal or state court residing in the State of California. The prevailing party 
in any such proceedings shall be entitled to recover its attorneys’ fee and litigation expenses 
in addition to other appropriate relief. If any provision of this License by Symantec shall be 
held to be unenforceable such holding shall not affect the enforceability of any other 
provision hereof. Waiver of any breach of this License by Symantec shall not be considered a 
waiver of any other or subsequent breach, the licensed software is a unique and valuable 
asset of Symantec and Symantec has the right to seek whatever equitable and legal redress 
which may be available to it for your breach of the provisions of the License. 

“Lightspeed” is a trademark of Lightspeed, Inc., and is used with its permission. 












SYMANTEC 


SYMANTEC. 

135 South Road 
Bedford, MA01730 





